本文目录导读：
是的，FastAPI 的自动生成 API 文档功能非常容易通过案例解释清楚，下面我用一个完整的、带有详细注释的案例来演示它如何工作,以及为什么这么强大。
核心原理（一句话概括）
FastAPI 基于 Python 的类型提示（Type Hints） 和 Pydantic 模型，自动分析你的代码，生成符合 OpenAPI 规范的 JSON 文件，并自动提供 Swagger UI 和 ReDoc 交互式文档。
案例：一个简单的图书管理 API
假设我们要创建一个管理图书的 API，支持 GET（获取列表）和 POST（创建图书）。
安装 FastAPI 和 Uvicorn
pip install fastapi uvicorn
编写代码 main.py
# 1. 导入必要的库
from fastapi import FastAPI, Query, Path, HTTPException
from pydantic import BaseModel
from typing import List, Optional
# 2. 创建 FastAPI 实例
app = FastAPI("我的图书管理系统",
description="这是一个学习 FastAPI 自动文档功能的示例 API",
version="1.0.0"
)
# 3. 定义数据模型（Pydantic 模型）
class Book(BaseModel):
"""图书数据模型"""
id: int str
author: str
summary: Optional[str] = None
class BookCreate(BaseModel):
"""创建图书时使用的模型（不需要 ID，由系统生成）""" str
author: str
summary: Optional[str] = None
# 4. 模拟数据库
fake_db = [
Book(id=1, title="Python编程", author="张三", summary="Python入门书籍"),
Book(id=2, title="FastAPI实战", author="李四"),
]
# 5. 定义路径操作（API端点）
# ----- GET 请求 -----
@app.get("/books", response_model=List[Book], tags=["图书管理"])
async def get_books(
skip: int = Query(0, description="跳过的记录数"),
limit: int = Query(10, description="返回的最大记录数"),
author: Optional[str] = Query(None, description="按作者筛选")
):
"""
获取图书列表，支持分页和按作者筛选。
- **skip**: 从第几条开始
- **limit**: 返回多少条
- **author**: 可选，过滤特定作者的图书
"""
books = fake_db
if author:
books = [book for book in books if book.author == author]
return books[skip: skip + limit]
# ----- POST 请求 -----
@app.post("/books", response_model=Book, status_code=201, tags=["图书管理"])
async def create_book(book: BookCreate):
"""
创建一本新图书。
- **book**: 包含图书信息的 JSON 请求体（title、author、summary）
- 返回：创建成功的图书对象（包含自动生成的 ID）
"""
new_id = len(fake_db) + 1
new_book = Book(id=new_id, **book.dict())
fake_db.append(new_book)
return new_book
# ----- GET 单本书 -----
@app.get("/books/{book_id}", response_model=Book, tags=["图书管理"])
async def get_book(
book_id: int = Path(..., description="要获取的图书 ID", ge=1)
):
"""
根据 ID 获取单本图书。
如果图书不存在，返回 404 错误。
"""
for book in fake_db:
if book.id == book_id:
return book
raise HTTPException(status_code=404, detail="图书未找到")
启动应用
uvicorn main:app --reload
见证奇迹：自动生成的交互式文档
启动后，访问以下两个 URL：
-
Swagger UI：
http://127.0.0.1:8000/docs- 你可以看到所有 API 端点，点击“Try it out”可以直接发送请求、查看响应。
- 自动显示了请求参数、请求体、响应模型、状态码、描述信息。
-
ReDoc：
http://127.0.0.1:8000/redoc另一种更干净、更适合阅读的文档布局。
这个案例如何解释了自动文档功能？
| 代码中的元素 | 自动文档中体现为什么？ |
|---|---|
app = FastAPI(, description="...") |
文档页面的标题和描述 |
函数文档字符串 """获取图书列表...""" |
端点的详细描述（Markdown 支持） |
参数 skip: int = Query(0, description="跳过的记录数") |
自动生成参数输入框、默认值、描述、类型 |
参数 book_id: int = Path(..., ge=1) |
路径参数，显示在 URL 中，并带有验证规则（ge=1） |
book: BookCreate 请求体 |
自动生成 JSON 请求体的 Schema（title, author, summary） |
response_model=List[Book] |
自动生成响应体的 Schema 和示例 |
status_code=201 |
在文档中清晰标注成功响应码 |
HTTPException(status_code=404, detail="图书未找到") |
文档自动生成 404 响应说明 |
tags=["图书管理"] |
对 API 进行分组，文档中按标签展示 |
为什么说这个功能很强大？
- 零配置：你只需要写标准的 Python 类型提示,不需要额外的配置文件。
- 代码即文档：文档与代码逻辑完全同步，修改代码，文档自动更新（因为有
--reload）。 - 双向受益：
- 开发者：开发时可以快速测试（Swagger UI 中的 Try it out）。
- 前端/调用方：可以直接复制示例代码（Swagger 支持多种语言代码生成）。
- 标准规范：背后生成的是标准的 OpenAPI JSON（访问
http://127.0.0.1:8000/openapi.json可看到），可以导入到 Postman、Apifox 等工具。
你的 Python 代码 (类型提示 + Pydantic 模型)
|
v
FastAPI 自动分析
|
v
OpenAPI Schema (openapi.json)
|
+-------> Swagger UI (/docs) [交互式调试]
|
+-------> ReDoc (/redoc) [美观文档]
|
+-------> 任何 OpenAPI 兼容工具 (Postman, Apifox, 代码生成器)这个案例通过一个常见的 CRUD 场景，完整展示了 FastAPI 如何从 Python 类型标注中“长出”一套完整的、可交互的 API 文档，这正是 FastAPI 最核心、最受欢迎的特性之一。
