FastAPI教程：API文档与交互 - 添加示例与描述

欢迎

FastAPI是一个现代、快速（高性能）的Python Web框架，专为构建API而设计。它的一大特色是自动生成交互式API文档，通过Swagger UI（在/docs）和ReDoc（在/redoc）提供。这些文档不仅美观，还允许开发者在线测试API。但为了使文档更清晰、更易用，我们可以添加描述和示例。本教程将详细指导你如何操作，适合新手入门。

1. FastAPI API文档概述

当你启动一个FastAPI应用时，它会基于你的代码自动生成OpenAPI规范的文档。这意味着无需手动编写，文档就会实时更新。默认情况下，你可以通过以下URL访问：

• Swagger UI: http://localhost:8000/docs – 提供交互式界面，可以发送请求和查看响应。
• ReDoc: http://localhost:8000/redoc – 提供更简洁的文档视图，适合阅读。

这些文档帮助开发者快速理解API的结构和使用方式。通过添加描述和示例，你可以进一步优化用户体验。

2. 添加描述到API

描述是文档中的重要部分，它解释了API的用途、参数和响应。在FastAPI中，你可以在多个层面添加描述。

2.1 路径操作描述

在定义API端点（路径操作）时，使用@app装饰器的summary和description参数。summary是简短标题，description是详细说明。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/", summary="获取物品列表", description="此端点返回数据库中所有物品的列表。支持分页和过滤功能。")
def read_items():
    return [{"name": "Item1"}, {"name": "Item2"}]

在Swagger UI中，这会显示为端点的摘要和详细描述，帮助用户一目了然。

2.2 Pydantic模型描述

Pydantic模型用于定义请求体和响应体的数据结构。使用Field类可以为每个字段添加描述。

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(..., description="物品的名称，例如：'笔记本电脑'")
    price: float = Field(..., gt=0, description="物品的价格，必须大于0，单位是美元。")
    is_offer: bool = Field(default=False, description="是否提供优惠，True表示有折扣。")

@app.post("/items/")
def create_item(item: Item):
    return item

这样，在文档中每个字段旁都会显示描述，减少误解。

3. 添加示例到API

示例数据展示了如何调用API，特别是对于复杂请求体，能大大降低学习曲线。FastAPI支持多种方式添加示例。

3.1 请求体示例

在路径操作函数中，使用Body函数的example参数为请求体添加具体示例。

from fastapi import Body

@app.post("/items/")
def create_item(
    item: Item = Body(
        ...,
        example={
            "name": "示例物品",
            "price": 19.99,
            "is_offer": True
        }
    )
):
    return item

在Swagger UI的请求体部分，这个示例会自动填充，用户可以直接修改并发送请求。

3.2 Pydantic模型示例

你可以在Pydantic模型的Config类中定义schema_extra来添加模型级别的示例。

class Item(BaseModel):
    name: str = Field(..., description="物品的名称")
    price: float = Field(..., gt=0, description="物品的价格")
    is_offer: bool = Field(default=False, description="是否提供优惠")

    class Config:
        schema_extra = {
            "example": {
                "name": "示例物品",
                "price": 25.5,
                "is_offer": False
            }
        }

这样，示例会应用到所有使用该模型的地方，包括请求和响应。

3.3 响应示例

FastAPI会自动使用响应模型中的示例。如果你定义了Pydantic模型并添加了示例，响应文档会显示它。

@app.get("/items/{item_id}", response_model=Item)
def read_item(item_id: int):
    # 模拟从数据库获取数据
    return Item(name=f"Item{item_id}", price=item_id * 5, is_offer=(item_id % 2 == 0))

在Swagger UI的响应部分，你会看到基于模型示例的预览。

4. 完整代码示例

下面是一个完整的FastAPI应用，整合了以上所有技术点。复制代码到你的环境中运行，然后访问http://localhost:8000/docs查看效果。

from fastapi import FastAPI, Body
from pydantic import BaseModel, Field

app = FastAPI(
    title="FastAPI示例API",
    description="这是一个展示如何添加描述和示例的教程应用。",
    version="1.0.0"
)

class Item(BaseModel):
    name: str = Field(..., description="物品的名称")
    price: float = Field(..., gt=0, description="物品的价格，必须为正数")
    is_offer: bool = Field(default=False, description="是否提供优惠")

    class Config:
        schema_extra = {
            "example": {
                "name": "示例笔记本电脑",
                "price": 999.99,
                "is_offer": True
            }
        }

@app.get("/items/", summary="获取所有物品", description="返回一个包含所有物品的列表。这个端点可以用于浏览库存。")
def read_items():
    return [
        {"name": "Item1", "price": 10.0, "is_offer": False},
        {"name": "Item2", "price": 20.0, "is_offer": True}
    ]

@app.post("/items/", summary="创建新物品", description="向数据库中添加一个新物品。需要提供名称、价格和优惠状态。")
def create_item(item: Item = Body(..., example={"name": "新手机", "price": 599.99, "is_offer": False})):
    # 这里通常有数据库插入逻辑
    return item

@app.get("/items/{item_id}", response_model=Item, summary="获取特定物品", description="根据物品ID检索详细信息。")
def read_item(item_id: int):
    # 模拟数据检索
    return Item(name=f"Item{item_id}", price=item_id * 10, is_offer=(item_id % 2 == 0))

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

运行后，打开http://localhost:8000/docs，你会看到每个端点都有描述，请求体和响应都有示例，交互性大大增强。

5. 总结与最佳实践

• 描述要清晰：为每个端点、参数和字段添加简洁明了的描述，避免技术术语过多，让新手也能理解。
• 示例要实用：提供真实场景的示例数据，如产品名称、价格等，帮助用户快速上手。
• 保持一致性：确保描述和示例与你的业务逻辑匹配，避免误导。
• 测试文档：定期使用Swagger UI测试你的API，确保文档和实际行为一致。
• 扩展功能：FastAPI还支持更多高级特性，如自定义响应模型、错误处理描述等，可以在官方文档中深入学习。

通过本教程，你应该掌握了如何在FastAPI中添加描述和示例来优化API文档。这不仅提升了开发效率，还让其他开发者更容易集成你的API。继续实践，探索FastAPI的更多强大功能吧！

下一步建议：尝试为你的实际项目添加描述和示例，并分享反馈。FastAPI社区活跃，有问题可以查阅官方文档或参与讨论。