FastAPI 提供了自动生成 API 文档的功能，但它不仅仅限于自动生成的文档。你还可以对 API 文档进行高度自定义，以便让 API 接口的描述更加清晰，帮助开发者和前端更好地理解如何与 API 交互。
本文将介绍如何自定义 API 路由描述信息 、为参数添加描述与例子 ，以及如何定制 响应模型的文档。通过这些自定义功能，你可以让 API 文档更符合业务需求和团队的开发标准。
1. 自定义 API 路由的描述信息
在 FastAPI 中，每个 API 路由（也就是请求路径）都可以附带描述信息，帮助开发者更好地理解接口的用途和行为。你可以使用 description 参数来为路由添加简要说明。
1.1 自定义描述
当你定义一个路由时，可以通过 description 参数为该路由添加详细的描述。以下是一个简单示例：
python
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}", description="获取指定 ID 的商品信息。")
async def read_item(item_id: int, query: str = None):
"""
- `item_id`: 商品的唯一标识符。
- `query`: 可选的查询字符串，用于搜索商品。
"""
return {"item_id": item_id, "query": query}在这个例子中：
- 我们使用
description参数为GET /items/{item_id}路由添加了说明："获取指定 ID 的商品信息"。 - 在函数内部，我们也通过文档字符串进一步说明了路由参数的含义。
当你访问 http://127.0.0.1:8000/docs 时，你将看到该路由的描述信息出现在文档中。
1.2 自定义操作描述
FastAPI 还允许你为 HTTP 操作（如 GET、POST、PUT 等）指定操作描述。使用 summary 和 description 来描述该操作的总体目标和具体细节。
python
@app.post("/items/", summary="创建新商品", description="提供商品信息并创建一个新的商品记录。")
async def create_item(item: Item):
return {"item_name": item.name, "item_price": item.price}在这里：
summary给出了操作的简短标题。description提供了对操作的详细说明。
2. 为参数添加描述与例子
FastAPI 支持为 API 参数添加详细描述以及示例。通过为请求参数添加 description 和 example，你可以使 API 文档更加易于理解。
2.1 为路径参数添加描述与例子
你可以为路径参数（如 URL 中的 {item_id}）添加详细的描述信息。
python
@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(..., description="商品的唯一标识符", example=123)):
return {"item_id": item_id}在上面的代码中：
Path用于定义路径参数。description参数描述了item_id的含义。example为该参数提供了一个示例值，在文档中展示给用户参考。
2.2 为查询参数添加描述与例子
除了路径参数，我们还可以为查询参数（如 query）添加描述和示例。
python
from fastapi import Query
@app.get("/items/")
async def read_item(query: str = Query(None, description="搜索商品的查询字符串", example="laptop")):
return {"query": query}在这里，Query 允许我们设置查询参数的描述和示例。查询参数 query 被描述为"搜索商品的查询字符串"，并提供了一个示例值 "laptop"。
2.3 为请求体的参数添加描述与例子
对于请求体（如 JSON 数据），你可以通过 Pydantic 模型来定义并添加详细描述。
python
from pydantic import BaseModel
class Item(BaseModel):
name: str = Field(..., description="商品名称", example="Laptop")
price: float = Field(..., description="商品价格", example=1200.99)
@app.post("/items/")
async def create_item(item: Item):
return {"item_name": item.name, "item_price": item.price}在这个例子中，Item 模型使用 Field 来为 name 和 price 字段添加描述和示例。这样，API 文档中会自动展示这些信息，帮助使用者理解请求体的结构和每个字段的含义。
3. 定制响应模型的文档
FastAPI 同样支持定制响应模型的文档，这可以帮助前端开发人员或 API 用户了解返回的数据结构。通过 Pydantic 模型，你可以为 API 的响应添加描述、示例以及详细的字段说明。
3.1 定义响应模型
假设我们定义一个返回商品信息的响应模型：
python
from pydantic import BaseModel
class ItemResponse(BaseModel):
item_id: int
name: str
price: float
class Config:
schema_extra = {
"example": {
"item_id": 123,
"name": "Laptop",
"price": 1200.99
}
}在上面的代码中：
ItemResponse是一个 Pydantic 模型，用于描述响应的结构。schema_extra用来提供一个响应的示例，帮助 API 用户了解返回的数据格式。
3.2 在路由中使用响应模型
在路由中，我们可以通过 response_model 参数来指定响应的 Pydantic 模型：
python
@app.get("/items/{item_id}", response_model=ItemResponse)
async def read_item(item_id: int):
return {"item_id": item_id, "name": "Laptop", "price": 1200.99}此时，访问 API 文档时，FastAPI 会自动展示 ItemResponse 模型的结构、字段描述以及示例数据。
3.3 定制不同状态码的响应文档
除了常规的成功响应外，FastAPI 还允许你为不同的 HTTP 状态码（如 400、404）定义响应模型。这对于详细描述错误响应非常有用。
python
from fastapi import HTTPException
@app.get("/items/{item_id}", response_model=ItemResponse, responses={404: {"description": "Item not found", "content": {"application/json": {"example": {"detail": "Item not found"}}}}})
async def read_item(item_id: int):
if item_id != 123:
raise HTTPException(status_code=404, detail="Item not found")
return {"item_id": item_id, "name": "Laptop", "price": 1200.99}在上面的代码中，我们为 404 错误添加了一个响应模型，定义了返回的错误消息格式和示例。这会使得 API 用户在查看文档时，能够清楚地了解当请求失败时返回的错误结构。
FastAPI 提供了非常灵活的 API 文档定制功能。通过 description、summary、example 和 Field 等参数，你可以：
- 自定义路由描述，使 API 文档更清晰、易懂。
- 为请求参数添加描述与示例，帮助使用者理解如何传递请求数据。
- 定制响应模型的文档，让前端开发人员清楚地了解接口的返回结构和示例数据。
这些功能不仅使得 FastAPI 自动生成的文档更加完整、易用，而且还提高了开发团队与前端人员、第三方使用者之间的协作效率。通过这些自定义选项，FastAPI 可以帮助你生成高度可读、可交互的 API 文档，提升开发体验和用户体验。
