在开发API时，自动生成的交互式文档是必不可少的工具。它能帮助开发者和使用者快速了解接口的功能、参数和返回值，甚至直接在浏览器中测试接口。FastAPI框架内置了强大的文档自动生成功能，基于Swagger UI和OpenAPI规范，让文档编写变得简单高效。
为什么需要自动生成文档？¶
想象一下，如果你的API没有文档，开发者需要手动查阅代码才能知道接口如何调用；如果接口参数复杂，用户可能会因不清楚格式而报错。而FastAPI的自动文档不仅能清晰展示接口结构，还支持交互式测试，大大降低了API的使用门槛。
Swagger UI与OpenAPI是什么关系？¶
- OpenAPI：是一种规范，定义了API的结构和交互方式，用JSON格式描述接口的路径、参数、响应等信息。FastAPI生成的文档本质上就是符合OpenAPI规范的JSON文件。
- Swagger UI：是一个基于OpenAPI规范的交互式文档工具，它会解析FastAPI生成的OpenAPI JSON文件，以可视化方式展示API文档，并提供“Try it out”功能直接测试接口。
- ReDoc：另一个基于OpenAPI的文档工具，与Swagger UI类似，但界面更简洁，适合需要更结构化文档的场景。FastAPI同样支持，访问
/redoc即可查看。
如何在FastAPI中启用文档？¶
创建一个最简单的FastAPI应用，运行后就能自动生成文档。以下是示例代码：
from fastapi import FastAPI
# 创建应用实例，可通过参数设置文档基本信息
app = FastAPI(
title="快速API示例",
description="这是一个使用FastAPI自动生成文档的演示",
version="1.0.0"
)
@app.get("/")
def read_root():
return {"message": "Hello World"}
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}
运行应用：uvicorn main:app --reload，然后访问：
- Swagger UI：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc
此时你会看到自动生成的文档，包含标题、描述、接口列表和参数说明。
实用技巧：让文档更清晰易用¶
1. 自定义文档基本信息¶
通过FastAPI构造函数的参数，可以设置文档的全局信息：
app = FastAPI(
title="电商API", # 文档标题
description="这是一个管理商品和订单的API接口，支持用户查询、下单等功能",
version="1.0.0", # 版本号
terms_of_service="https://example.com/terms", # 服务条款链接
contact={"name": "开发团队", "email": "dev@example.com"} # 联系人信息
)
2. 详细描述接口和参数¶
接口的描述、参数说明可以通过三种方式添加：
- 函数Docstring：直接在函数内写注释，FastAPI会自动解析到文档中。
- 参数装饰器：使用Path、Query等工具类添加参数描述。
- 接口装饰器：用description、summary、tags等参数。
示例：
from fastapi import Path, Query
@app.get("/items/{item_id}",
tags=["商品查询"], # 按标签分类，方便筛选
summary="查询商品详情", # 接口简短描述
description="根据商品ID查询详细信息<br/>- **item_id** 必须为整数<br/>- 支持返回商品库存状态")
def read_item(
item_id: int = Path(...,
title="商品ID",
description="商品的唯一标识（1-1000）",
ge=1, le=1000), # ge=1表示大于等于1
q: str = Query(None,
title="搜索关键词",
description="可选，用于模糊匹配商品名称")
):
return {"item_id": item_id, "q": q}
3. 隐藏不需要公开的接口¶
如果某些接口仅内部使用（如调试接口），可以通过include_in_schema=False隐藏：
@app.get("/internal/debug", include_in_schema=False) # 隐藏该接口
def internal_debug():
return {"debug": "This is internal only"}
4. 用响应模型规范返回格式¶
使用Pydantic模型定义接口返回数据，文档会自动生成示例和参数结构：
from pydantic import BaseModel
class ItemResponse(BaseModel):
name: str
price: float
stock: int = 0 # 默认值
@app.get("/items/{item_id}", response_model=ItemResponse)
def read_item(item_id: int):
return {"name": "手机", "price": 2999.99, "stock": 100}
5. 显示错误信息¶
通过HTTPException定义接口可能的错误状态码，文档会自动标注：
from fastapi import HTTPException
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id > 100:
raise HTTPException(
status_code=400,
detail="商品ID不能超过100"
)
return {"item_id": item_id}
总结¶
FastAPI的自动文档功能基于OpenAPI规范，通过Swagger UI和ReDoc提供直观的接口展示。掌握以下关键点能让文档更实用：
- 用FastAPI构造函数参数设置全局信息（标题、描述等）；
- 通过函数注释、Path/Query等工具类详细描述接口和参数；
- 用tags对接口分类，便于筛选；
- 隐藏内部接口，避免文档混乱；
- 使用Pydantic模型规范返回格式，自动生成示例。
自动生成的文档不仅能节省手动编写的时间，还能保证接口信息与代码一致，让团队协作和用户使用更顺畅。
通过以上技巧，即使是初学者也能快速上手FastAPI的文档生成，让你的API变得更专业、更易用！