FastAPI OpenAPI文档支持中文和Markdown需五步：一、初始化时用UTF-8编码设置中文title/description；二、路由函数用三重双引号docstring并启用description_from_docstring；三、Pydantic字段用Field(description=)注入中文Markdown；四、路由装饰器中用summary/description参数覆盖；五、确保/openapi.json中中文未被Unicode转义且前端正确解析。
如果您使用 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 的描述。
HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
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 符号完整可见且未损坏。
