FastAPI 如何生成自动文档？

Question

FastAPI 如何生成自动文档？

Accepted Answer

FastAPI **从您的代码自动生成交互式 API 文档** — 您的路由、参数和 Pydantic 模型被转换为 OpenAPI 架构，它支持两个可浏览的文档 UI（Swagger UI 和 ReDoc），完全无需额外工作。

## 获得免费文档

```python
class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="Price in USD")

@app.post("/items", tags=["items"], summary="Create an item")
def create_item(item: Item):
    """Create a new item with a name and price."""   # docstring → endpoint description
    return item
```

只需编写带类型注解的端点和模型，FastAPI 就会生成完整的文档 — 无需编写或维护单独的文档文件。

## 两个内置文档 UI

```text
/docs   → Swagger UI — interactive: browse endpoints AND test them in the browser
          (fill in parameters, send requests, see responses live)
/redoc  → ReDoc — a clean, readable reference-style view
/openapi.json → the raw OpenAPI schema (usable to generate client SDKs, etc.)
```

访问 `/docs`，您可以浏览每个端点，查看必需参数和响应结构，并**直接在浏览器中发送真实请求** — 这在开发过程中和 API 使用者方面都非常有价值。

## 文档内容的来源

```text
Route decorators → paths, HTTP methods, tags, summaries
Type hints       → parameter types, required/optional
Pydantic models  → request/response schemas, field constraints & descriptions
Docstrings       → endpoint descriptions
Field(..., description=, example=) → field-level docs and examples
```

所有内容都来自您已经编写的代码 — 文档自动与实现**保持同步**。

## 丰富文档

```python
app = FastAPI(title="My API", version="1.0", description="...")
@app.get("/x", response_model=Item, responses={404: {"description": "Not found"}})
```

## 为什么这很重要

自动交互式文档是 FastAPI 最受欢迎的功能之一，也是它流行的主要原因。

由于文档直接从您的代码（路由、类型提示、Pydantic 模型、文档字符串）生成，它们总是**与实际实现保持同步** — 消除了手写文档存在的文档过期问题，这是困扰许多项目的顽疾。

交互式 Swagger UI（`/docs`）让开发者和 API 使用者能够在浏览器中探索和**实时测试端点**，极大地改善了开发者体验，减少了集成摩擦。

生成的 OpenAPI 架构还可以驱动客户端 SDK 生成和契约测试。

只需编写良好的类型化代码，就能获得专业、准确、交互式的 API 文档 — 本质上是免费的 — 这是一个重要的生产力和质量胜利，使其成为 FastAPI 的重要且独特的功能。