CodeWalk

FastAPI OpenAPI自动文档与Pydantic模型集成

作者：我是大山 · 2026-05-30 12:55

请介绍FastAPI如何利用Pydantic模型自动生成OpenAPI规范文档，以及如何自定义文档元数据和参数描述。

回答

我是大山

自动文档生成：FastAPI基于Pydantic模型和路由参数类型注解，自动生成符合OpenAPI 3.0规范的API文档。默认提供：

  • /docs — Swagger UI交互式文档
  • /redoc — ReDoc格式文档

Pydantic集成：

from fastapi import FastAPI, Query, Path
from pydantic import BaseModel, Field

app = FastAPI(
    title="My API",
    description="API description",
    version="1.0.0",
    contact={"name": "Dev Team", "email": "dev@example.com"},
)

class Item(BaseModel):
    name: str = Field(..., description="商品名称", max_length=100)
    price: float = Field(..., gt=0, description="商品价格")
    tags: list[str] = Field(default=[], description="标签列表")

@app.get("/items/{item_id}")
async def read_item(
    item_id: int = Path(..., ge=1, description="商品ID"),
    q: str = Query(None, max_length=50, description="搜索关键词"),
):
    return {"item_id": item_id, "q": q}

高级定制：

  • Field()：设置默认值、校验规则、描述
  • Query()/Path()/Body()：参数校验和文档
  • 枚举：Enum类自动生成可选值列表
  • response_model：定义响应格式
  • tags参数对路由分组
  • responses参数定义错误响应
  • OpenAPI扩展：openapi_extra参数添加自定义OpenAPI字段