第3.5章:Swagger 自动文档
学习时间: 30分钟
1. API 文档:空间站操作手册
想象一下,你是一名刚抵达国际空间站的新宇航员。你如何知道每个开关的功能以及如何操作机械臂?你需要一份详细且最新的操作手册。
API 文档对开发者来说就是这样一份手册。它解释了:
- 有哪些“对接端口”(endpoints)可用。
- 可以发送哪些“命令”(HTTP 方法)。
- 需要传输哪些“货物”(数据)。
- 预期会收到哪些“遥测数据”(响应)。
问题在于,手动编写文档耗时、枯燥,而且几乎总是会过时。
💡 太空类比:
手动文档就像纸质图纸,它们躺在档案室里,空间站改造后也不会更新。 FastAPI 自动文档是指挥中心(ЦУП)的交互式显示屏,在空间站每次变更后都会实时更新。
2. FastAPI 的魔力:它是如何工作的?
FastAPI 基于你的代码为你完成了所有“脏活累活”。它会扫描:
- 路由: 所有
@app.get
、@app.post
等装饰器。 - 参数: 路径参数(
ship_id: int
)和查询参数。 - Pydantic 模型: 你的“蓝图”(
Spaceship
、SpaceshipCreate
)。 - 文档字符串 (docstrings): 你用三重引号编写的描述。
基于这些数据,FastAPI 会生成符合 OpenAPI 标准(以前称为 Swagger)的模式,然后通过两个美观的界面展示它。
3. 探索“指挥中心显示屏”:Swagger UI
Swagger UI 是一个交互式界面,它不仅允许你阅读文档,还可以直接从浏览器测试 API。
打开 http://127.0.0.1:8000/docs
你会看到:
- 端点列表: 按标签分组(默认按资源名称),并用 HTTP 方法的颜色着色。
- 描述: 你的文档字符串(
"""..."""
)中的文本会显示为端点描述。 - 参数: 显示端点期望哪些参数(如
ship_id
)、它们的类型和是否必填。 - 请求体 (Request Body): 对于
POST
和PUT
请求,显示从你的 Pydantic 模型(SpaceshipCreate
)生成的 JSON 模式。 - 响应 (Responses): 显示可能的状态码和基于
response_model
的响应模式。 - “Try it out”按钮: 允许你填写参数并向你的服务器发送实际请求。
4. 改进文档:标签和描述
让我们让文档看起来更专业。
步骤 1:在 FastAPI
中添加元数据
在创建 app
时,你可以传递关于 API 的一般信息。
修改 main.py
中的 app = FastAPI()
行:
# main.py
app = FastAPI(
title="Fleet Management API",
description="API 用于管理航天器舰队。",
version="1.0.0",
)
步骤 2:使用标签对端点进行分组 你可以为每个端点添加标签,以便按逻辑对其进行分组。
在装饰器中添加 tags
参数:
# GET /spaceships
@app.get("/spaceships", response_model=List[Spaceship], tags=["航天器"])
# ...
# GET /spaceships/{ship_id}
@app.get("/spaceships/{ship_id}", response_model=Spaceship, tags=["航天器"])
# ...
# POST /spaceships
@app.post("/spaceships", response_model=Spaceship, status_code=201, tags=["航天器"])
# ...
# PUT 和 DELETE 依此类推
5. 另一种视图:ReDoc
FastAPI 提供了另一个“开箱即用”的文档界面——ReDoc。它交互性较低,但通常被认为更具可读性,非常适合静态文档。
打开 http://127.0.0.1:8000/redoc
你会看到一个三列布局,包含导航、端点描述和数据模式。这是向你的“客户”(例如前端团队)提供文档的好方法。
巩固练习小测验
🚀 本章总结:
你已经了解了 FastAPI 最强大的“超能力”之一——毫不费力地创建文档。
- 📖 你的 API 现在拥有两种最新的文档视图:Swagger UI 和 ReDoc。
- 🔬 文档是交互式的,允许你即时测试 API。
- 🏷️ 你学会了如何通过元数据和标签来改进它。
操作手册已就绪,并且始终保持最新! 在本节的最后一章,我们将学习如何处理“太空异常”——错误和不正确的数据。
📌 检查:
- 确保在
http://127.0.0.1:8000/docs
地址显示标题、描述和按标签分组的端点。- 检查“Schemas”部分是否显示你的
Spaceship
模型。- 打开
http://127.0.0.1:8000/redoc
并评估替代视图。⚠️ 如果更改未显示:
- 确保你已保存
main.py
文件。- 检查
uvicorn
服务器是否已使用--reload
标志启动并成功重新加载。