Skip to content

第3.5章:Swagger 自动文档

学习时间: 30分钟


1. API 文档:空间站操作手册

想象一下,你是一名刚抵达国际空间站的新宇航员。你如何知道每个开关的功能以及如何操作机械臂?你需要一份详细且最新的操作手册

API 文档对开发者来说就是这样一份手册。它解释了:

  • 有哪些“对接端口”(endpoints)可用。
  • 可以发送哪些“命令”(HTTP 方法)。
  • 需要传输哪些“货物”(数据)。
  • 预期会收到哪些“遥测数据”(响应)。

问题在于,手动编写文档耗时、枯燥,而且几乎总是会过时。

💡 太空类比:

手动文档就像纸质图纸,它们躺在档案室里,空间站改造后也不会更新。 FastAPI 自动文档指挥中心(ЦУП)的交互式显示屏,在空间站每次变更后都会实时更新。


2. FastAPI 的魔力:它是如何工作的?

FastAPI 基于你的代码为你完成了所有“脏活累活”。它会扫描:

  1. 路由: 所有 @app.get@app.post 等装饰器。
  2. 参数: 路径参数(ship_id: int)和查询参数。
  3. Pydantic 模型: 你的“蓝图”(SpaceshipSpaceshipCreate)。
  4. 文档字符串 (docstrings): 你用三重引号编写的描述。

基于这些数据,FastAPI 会生成符合 OpenAPI 标准(以前称为 Swagger)的模式,然后通过两个美观的界面展示它。


3. 探索“指挥中心显示屏”:Swagger UI

Swagger UI 是一个交互式界面,它不仅允许你阅读文档,还可以直接从浏览器测试 API

打开 http://127.0.0.1:8000/docs

你会看到:

  • 端点列表: 按标签分组(默认按资源名称),并用 HTTP 方法的颜色着色。
  • 描述: 你的文档字符串("""...""")中的文本会显示为端点描述。
  • 参数: 显示端点期望哪些参数(如 ship_id)、它们的类型和是否必填。
  • 请求体 (Request Body): 对于 POSTPUT 请求,显示从你的 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 依此类推
现在,你所有的 CRUD 操作都将整齐地分组在“航天器”标题下。


5. 另一种视图:ReDoc

FastAPI 提供了另一个“开箱即用”的文档界面——ReDoc。它交互性较低,但通常被认为更具可读性,非常适合静态文档。

打开 http://127.0.0.1:8000/redoc

你会看到一个三列布局,包含导航、端点描述和数据模式。这是向你的“客户”(例如前端团队)提供文档的好方法。


巩固练习小测验

1. FastAPI 生成文档的依据是...

2. FastAPI 自动文档的基础标准是什么?

3. Swagger UI 交互式文档默认在哪个 URL 下可用?

4. 装饰器 `@app.get` 中的 `tags` 参数用于:

5. ReDoc 是...


🚀 本章总结:

你已经了解了 FastAPI 最强大的“超能力”之一——毫不费力地创建文档。

  • 📖 你的 API 现在拥有两种最新的文档视图:Swagger UIReDoc
  • 🔬 文档是交互式的,允许你即时测试 API。
  • 🏷️ 你学会了如何通过元数据和标签来改进它。

操作手册已就绪,并且始终保持最新! 在本节的最后一章,我们将学习如何处理“太空异常”——错误和不正确的数据。

📌 检查:

  • 确保在 http://127.0.0.1:8000/docs 地址显示标题、描述和按标签分组的端点。
  • 检查“Schemas”部分是否显示你的 Spaceship 模型。
  • 打开 http://127.0.0.1:8000/redoc 并评估替代视图。

⚠️ 如果更改未显示:

  • 确保你已保存 main.py 文件。
  • 检查 uvicorn 服务器是否已使用 --reload 标志启动并成功重新加载。