FastAPI中文OpenAPI文档设置方法

本文详解了在 FastAPI 中实现 OpenAPI 文档原生支持中文显示与 Markdown 渲染的完整实践路径——从应用初始化时的 UTF-8 编码配置和中文元信息设置，到路由 docstring 自动提取、Pydantic 字段级中文 Markdown 注释、装饰器参数精准覆盖，再到 /openapi.json 的编码验证与前端渲染保障，五步环环相扣，帮你彻底告别文档中英文混杂、格式丢失、中文乱码或 Markdown 不渲染的痛点，让 API 文档既专业易读，又具备技术文档所需的富文本表现力。

如果您使用 FastAPI 构建 API，但 OpenAPI 文档中接口描述、参数说明或响应示例显示为英文或纯文本，无法正确渲染中文和 Markdown 格式，则可能是由于文档元数据未正确配置或未启用富文本支持。以下是实现 OpenAPI 文档显示中文且支持 Markdown 渲染的多种方法：

一、在 FastAPI 实例初始化时设置中文标题与描述

FastAPI 默认通过 title 和 description 参数注入根级文档元信息，这些字段支持 Unicode 字符和 Markdown 语法（如 **加粗**、*斜体*、代码块、列表等），但需确保字符串本身为 UTF-8 编码且未被转义。

1、在创建 FastAPI() 实例时，直接传入中文字符串作为 title 和 description 参数。

2、在 description 中使用标准 Markdown 语法编写说明，例如换行用空行分隔，标题用 ##，代码块用三个反引号包裹。

3、确保 Python 源文件顶部声明编码：在文件第一行或第二行添加 # -*- coding: utf-8 -*-。

二、为每个路由函数添加中文 docstring 并启用 description_from_docstring

FastAPI 可自动将函数的文档字符串（docstring）提取为接口的 description，前提是启用 description_from_docstring=True 配置，并确保 docstring 使用三重双引号包裹且含 Markdown 内容。

1、在定义 @app.get() 等路由装饰器时，在其上方紧邻位置写三重双引号 docstring。

2、docstring 中使用中文撰写，并嵌入 Markdown 元素，如 **请求说明**、`application/json`、无序列表以 - 开头。

3、启动应用前，在 FastAPI() 初始化中显式设置 description_from_docstring=True（该参数在较新版本中默认为 True，但仍建议显式声明）。

三、使用 Pydantic v2 的 model_config 设置字段中文注释

当使用 Pydantic 模型（如 BaseModel）定义请求体或响应体时，字段级中文说明不会自动出现在 OpenAPI 中，需通过 model_config 或字段 description 参数注入，且该 description 支持 Markdown。

1、在 Pydantic 模型字段定义中，使用 Field(description="用户昵称，**最多12个汉字**") 显式指定带 Markdown 的描述。

2、若使用 Pydantic v2，也可在 model_config = ConfigDict(json_schema_extra={...}) 中为字段补充 description 值。

3、确保字段 description 字符串内容为原始中文 Markdown，不经过 HTML 转义或双重编码。

四、自定义 OpenAPI Schema 中的 summary 和 description 字段

FastAPI 允许通过 summary 和 description 参数覆盖单个端点的 OpenAPI 属性，这两个参数均支持中文和 Markdown，优先级高于 docstring。

1、在路由装饰器中直接传入 summary="获取用户列表" 和 description="返回分页的用户数据，包含 `id`、`name` 和 `status` 字段。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | **必填**，用户真实姓名 |"。

2、注意：多行字符串中换行符需保留，Markdown 表格、代码块等结构必须符合 CommonMark 规范。

3、关键提示：避免在 description 中使用未闭合的反引号或嵌套过深的缩进，否则会导致 Swagger UI 解析失败而显示为空白。

五、确保静态资源与前端渲染环境支持 UTF-8 和 Markdown 解析

FastAPI 内置的 Swagger UI 和 ReDoc 均基于 JavaScript 渲染 OpenAPI JSON，其对中文和 Markdown 的支持依赖于 JSON 数据本身的编码正确性及 UI 组件的解析能力。

1、检查生成的 /openapi.json 响应体，确认 info.title、paths.*.get.description 等字段值为原始中文字符串，而非 Unicode 转义序列（如 \u7528\u6237）。

2、若发现 JSON 中出现 Unicode 转义，需在 FastAPI 初始化时设置 default_response_class=UJSONResponse 并禁用自动转义，或改用标准 JSONResponse 并确保 ensure_ascii=False 已启用（FastAPI 默认已设）。

3、重要验证步骤：直接访问 /openapi.json 查看 raw JSON 输出，确认中文和 Markdown 符号完整可见且未损坏。

今天关于《FastAPI中文OpenAPI文档设置方法》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！