FastAPI框架默认生成的OpenAPI文档以英文展示，且不支持Markdown格式的内容渲染，在实际开发尤其是面向国内用户的项目中，往往需要调整配置让文档显示中文并支持Markdown，提升文档的可读性。
基础配置：让OpenAPI文档显示中文
要让文档的基础信息显示中文，需要自定义FastAPI的openapi配置，修改文档的标题、描述等基础字段，同时可以配置文档的版本信息。
首先创建FastAPI实例时，可以传入基础的文档信息，这些字段支持直接填写中文：
from fastapi import FastAPI
app = FastAPI(
title="用户管理接口", # 文档标题，支持中文
description="提供用户相关的增删改查接口，支持用户信息的批量操作", # 文档整体描述，支持中文
version="1.0.0" # 接口版本
)
@app.get("/users")
def get_users():
return {"msg": "获取用户列表成功"}
运行项目后访问/docs路径，就能看到文档标题和整体描述已经显示为设置的中文内容。
进阶配置：支持Markdown格式渲染
FastAPI的OpenAPI文档基于Swagger UI，默认不会渲染Markdown内容，需要在自定义OpenAPI配置中添加Markdown相关的支持配置，同时修改Swagger UI的参数。
自定义OpenAPI方法
通过重写FastAPI的openapi方法，添加swagger_ui_parameters配置，开启Markdown渲染支持：
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI(
title="用户管理接口",
description="## 接口说明n- 所有接口都需要携带`Authorization`请求头n- 返回格式统一为JSON结构",
version="1.0.0"
)
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
# 生成默认的OpenAPI schema
openapi_schema = get_openapi(
title=app.title,
version=app.version,
description=app.description,
routes=app.routes,
)
# 添加Swagger UI配置，开启Markdown支持
openapi_schema["swagger_ui_parameters"] = {
"markdown": True # 开启Markdown渲染
}
app.openapi_schema = openapi_schema
return app.openapi_schema
# 将自定义的openapi方法绑定到app实例
app.openapi = custom_openapi
@app.get("/users/{user_id}")
def get_user(user_id: int):
"""
获取单个用户详情
## 请求参数说明
- `user_id`: 用户唯一ID，类型为整型
## 返回示例
```json
{
"id": 1,
"name": "张三",
"age": 25
}
```
"""
return {"id": user_id, "name": "张三", "age": 25}
接口描述中编写Markdown内容
在接口的文档字符串（docstring）中可以直接编写Markdown格式的内容，包括标题、列表、代码块、加粗等格式，开启Markdown支持后这些内容会被正确渲染。
比如上面的get_user接口的docstring中使用了二级标题、无序列表、代码块等Markdown语法，访问文档页面就能看到对应的渲染效果。
注意事项
- Markdown语法需要符合标准格式，避免出现未闭合的标记导致渲染异常
- 如果需要在参数描述中使用Markdown，可以在Path、Query等参数的description字段中编写Markdown内容，同样会被渲染
- 若部署时文档出现样式问题，可以检查是否正确配置了swagger_ui_parameters的markdown参数
完整示例验证
运行上述完整代码后，访问http://127.0.0.1:8000/docs，可以看到：
- 文档标题、整体描述都显示为中文
- 接口描述中的Markdown内容（标题、列表、代码块）都被正确渲染
- 参数说明中的Markdown格式也能正常展示
这样就完成了FastAPI的OpenAPI文档中文显示和Markdown支持的全部配置，开发者可以根据实际需求调整文档的内容和格式。