FastAPI怎么汉化Swagger UI和Redoc文档页面-Python教程-PHP中文网

FastAPI的Swagger UI和ReDoc中文支持靠前端配置而非后端翻译：Swagger UI 5.x+需在swagger_ui_parameters中显式设"layout":"BaseLayout"及"lang":"zh-cn"；ReDoc需URL加?lang=zh；推荐本地化静态资源避免CDN失败。

fastapi怎么汉化swagger ui和redoc文档页面

FastAPI 的 Swagger UI 和 ReDoc 默认是英文界面，但它们本身支持多语言——关键不是改 FastAPI 代码，而是往 swagger_ui_parameters 或 redoc_url 对应的前端资源里注入语言配置。国内开发者常误以为要“翻译模板”或“重写 HTML”，其实只要配对参数、加载对应语言包，就能生效。

Swagger UI 怎么启用中文（含版本兼容要点）

Swagger UI 5.x+ 内置中文支持，靠的是 swagger_ui_parameters 中的 layout 和 presets 配合语言标识。不加配置时它会按浏览器 Accept-Language 自动 fallback，但在国内常因 CDN 加载失败或未显式声明导致仍显示英文。

必须显式设置 "layout": "BaseLayout"，否则中文 label 可能不渲染
加上 "defaultModelRendering": "model" 和 "docExpansion": "list" 能避免模型折叠后中文字段名被截断
关键语言参数：在 swagger_ui_parameters 里加 "supportedSubmitMethods": ["get","post","put","delete","patch"]（部分旧版 UI 会因缺失该字段跳过 i18n 初始化）
如果你用的是 Swagger UI https://cdn.jsdelivr.net/npm/swagger-ui-dist@4.15.5/swagger-ui-bundle.js 并补上 lang: "zh-cn" 参数——但更推荐升级 FastAPI + 改用本地化方案，避免 CDN 不稳定

Redoc 怎么强制中文显示

ReDoc 的多语言支持比 Swagger UI 更隐蔽：它不依赖 Accept-Language，也不暴露 lang 参数，而是靠加载时 URL 的 hash 或 query string 控制。直接访问 /redoc 通常不会触发中文，除非你主动传参。

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

最简单有效的方式：把 Redoc 页面 URL 改成 /redoc?lang=zh，它会自动加载内置中文文案（ReDoc v2.0+ 均支持）

若想默认就走中文，初始化 FastAPI 时不要只改路径，要配合中间件重定向：

from fastapi import Request, Response
from starlette.middleware.base import BaseHTTPMiddleware

class RedocLangMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        if request.url.path == "/redoc" and not request.url.query:
            return Response(status_code=302, headers={"Location": "/redoc?lang=zh"})
        return await call_next(request)

注意：ReDoc 的中文翻译覆盖不如 Swagger UI 全，比如 deprecated 字段、examples 区域的提示语可能仍是英文，这是它的已知限制，不是配置问题

为什么本地化静态资源能彻底解决汉化+加载失败问题

单纯配参数治标不治本。国内访问 cdn.jsdelivr.net 经常超时或 403，导致 Swagger UI/ReDoc 的 JS 文件加载失败，整个文档页白屏——这时候即使写了 lang="zh" 也根本跑不起来。

真正可靠的方案是：下载官方发布的 swagger-ui-bundle.js 和 redoc.standalone.js，放进项目 static/ 目录，再通过 FastAPI 的 app.mount() 暴露静态路由

然后在初始化时指定本地路径：

app = FastAPI(
    docs_url=None,
    redoc_url=None,
)
app.mount("/static/swagger", StaticFiles(directory="static/swagger-ui"), name="swagger")
app.mount("/static/redoc", StaticFiles(directory="static/redoc"), name="redoc")

接着自定义路由返回 HTML，在页面里用 <script src="/static/swagger/swagger-ui-bundle.js"></script> 加载，并传入 lang: "zh-cn"；Redoc 同理，URL 末尾拼 ?lang=zh
这个做法绕过了所有 CDN 依赖，也让你完全掌控语言包版本——比如 Swagger UI v5.17.10 的中文翻译比 v5.9.0 准确得多，而 FastAPI 默认绑的是老版本

最容易被忽略的一点：OpenAPI JSON 本身不含语言信息，所有汉化都发生在前端 JS 渲染层。所以改 title、description 这些字段只能影响文档头部，接口参数名、响应字段说明是否中文，取决于你用的 Swagger UI / ReDoc 版本及其内置翻译完整性，而不是 FastAPI 的 Python 代码。