11 FastAPI文档自定义

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 文档，提升开发体验和用户体验。