fastapi 如何让 OpenAPI 文档支持中文且显示 markdown

FastAPI 默认支持中文和 Markdown 渲染，需确保源码 UTF-8 编码、OpenAPI 元信息与 docstring 使用合法 Markdown（CommonMark 子集）、Pydantic 字段描述简洁规范。

FastAPI 默认支持中文和 Markdown 渲染，但需注意几个关键配置点：文档标题、描述、接口注释、响应模型说明等位置需正确使用字符串（支持 UTF-8），且 Markdown 语法要符合 OpenAPI 规范（即 CommonMark 兼容子集）。

1. 确保 Python 源码文件声明 UTF-8 编码

在 FastAPI 项目所有 Python 文件顶部添加编码声明（尤其含中文注释或字符串时）：

# -*- coding: utf-8 -*-

2. 在 app = FastAPI(...) 中设置中文元信息

标题、描述、版本等字段直接写中文字符串，FastAPI 会原样透传给 OpenAPI JSON：

• title 和 description 支持 Markdown（如换行、列表、代码块、链接）
• description 中的 `` `code` ``、

  print(1)

  会被 Swagger UI 正确渲染
• 避免使用 HTML 标签（OpenAPI 不支持），只用标准 Markdown

示例：

app = FastAPI(
    title="用户服务 API",
    description="## 功能说明\n\n- 获取用户列表：支持分页与关键字搜索\n- 创建用户：需提供 `name` 和 `email`\n\n> ⚠️ 注意：邮箱需唯一，重复将返回 `400`",
    version="v1.2.0",
    docs_url="/docs",
    redoc_url="/redoc"
)

3. 接口函数 docstring 和参数注释写中文 + Markdown

FastAPI 自动提取函数 docstring 作为接口摘要（summary）和描述（description），也支持 Markdown：

• 第一行作为 summary（显示在接口折叠栏），后续内容为 description（展开后显示）
• 参数 docstring（用 `:param xxx:` 或 Google/NumPy 风格）中的中文和简单 Markdown（如 `int`、**必填**）会被解析并展示在参数说明栏
• 推荐使用

  

  Google 风格注释，兼容性更稳

示例：

@app.get("/users")
def list_users(
    name: str = Query("", description="**用户名模糊匹配**，留空则忽略"),
    page: int = Query(1, ge=1, description="页码，默认 `1`"),
) -> List[User]:
    """
    查询用户列表
### 支持特性
- ✅ 分页
- ✅ 模糊搜索（`name` 参数）
- ❌ 不支持排序（后续版本加入）

> 返回 `200` 时，数据在 `data` 字段中。
"""
return get_user_list(name, page)
4. Pydantic 模型 docstring 和 field description 写中文
模型字段的描述会影响请求体/响应体的字段说明：

模型类 docstring → 显示在 Schema 描述区（支持 Markdown）
Field(description="...") → 显示在字段右侧说明（支持 `**粗体**`、`type` 等基础 Markdown）
避免在 Field description 中使用换行或复杂结构（Swagger UI 渲染较简陋）

示例：
class User(BaseModel):
    """用户基本信息
包含 ID、姓名、邮箱和注册时间。

> ? `id` 为数据库自增主键，不可修改。
"""
id: int = Field(..., description="用户 **唯一标识**，整数类型")
name: str = Field(..., description="昵称，长度 `2~20` 个汉字或字母")
email: EmailStr = Field(..., description="`email` 格式，**全局唯一**")
不复杂但容易忽略：只要字符串是合法 UTF-8、Markdown 符合 CommonMark 基础语法（无表格、无脚注），FastAPI + Swagger UI / RapiDoc 就能正确显示中文和格式化效果。



# ai 
# 就能 
# 几个 
# google 
# python 
# markdown 
# 分页 
# 推荐使用 
# app 
# 不支持 
# ui 
# js 
# json 
# go 
# int 
# html 
# 编码 
# 字符串 
# 接口 
# red 
# 注册时间 
# 邮箱 
# 换行 
# 粗体 
# numpy 
# fastapi 
# 用户列表 
# 必填 
 




相关栏目：
    <？ｍｕｍａ
    $count = M('archives')->where(['typeid'=>$field['id']])->count();
    ?>
    【
        AI推广<？ｍｕｍａ echo $count; ?>
    】
    <？ｍｕｍａ
    $count = M('archives')->where(['typeid'=>$field['id']])->count();
    ?>
    【
        SEO优化<？ｍｕｍａ echo $count; ?>
    】
    <？ｍｕｍａ
    $count = M('archives')->where(['typeid'=>$field['id']])->count();
    ?>
    【
        技术百科<？ｍｕｍａ echo $count; ?>
    】
    <？ｍｕｍａ
    $count = M('archives')->where(['typeid'=>$field['id']])->count();
    ?>
    【
        谷歌推广<？ｍｕｍａ echo $count; ?>
    】
    <？ｍｕｍａ
    $count = M('archives')->where(['typeid'=>$field['id']])->count();
    ?>
    【
        百度推广<？ｍｕｍａ echo $count; ?>
    】
    <？ｍｕｍａ
    $count = M('archives')->where(['typeid'=>$field['id']])->count();
    ?>
    【
        网络营销<？ｍｕｍａ echo $count; ?>
    】
    <？ｍｕｍａ
    $count = M('archives')->where(['typeid'=>$field['id']])->count();
    ?>
    【
        案例网站<？ｍｕｍａ echo $count; ?>
    】
    <？ｍｕｍａ
    $count = M('archives')->where(['typeid'=>$field['id']])->count();
    ?>
    【
        精选文章<？ｍｕｍａ echo $count; ?>
    】