FastAPI自学教程（88） - 扩展OpenAPI文档指南

1.基础扩展方法

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="自定义API文档",
        version="2.5.0",
        description="包含自定义扩展的OpenAPI文档",
        routes=app.routes,
    )
    # 添加ReDoc扩展的logo配置
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

通过覆盖app.openapi方法实现文档生成逻辑自定义
使用get_openapi工具函数生成基础文档结构，支持参数：
- title：文档标题（必填）
- version：API版本号（必填）
- routes：路由列表（自动从app.routes获取）
- description：详细描述文本（可选）

流程图展示生成流程：

graph TD
  A[请求/openapi.json] --> B{是否缓存存在?}
  B -->|是| C[返回缓存文档]
  B -->|否| D[调用get_openapi生成]
  D --> E[添加自定义扩展]
  E --> F[缓存文档]
  F --> G[返回生成文档]

2.高级配置技巧

2.1 操作标识符定制

from fastapi.routing import APIRoute

def use_route_names_as_operation_ids(app: FastAPI):
    for route in app.routes:
        if isinstance(route, APIRoute):
            route.operation_id = route.name

app = FastAPI()
use_route_names_as_operation_ids(app)

将路由函数名作为operationId，提升客户端生成代码可读性
需确保所有路径操作函数名称全局唯一

2.2 接口文档排除

1
2
3

@app.get("/internal/metrics", include_in_schema=False)
async def get_metrics():
    return {"cpu_usage": 0.75}

使用include_in_schema=False隐藏敏感接口文档
适用于监控端点、内部调试接口等场景

3.生产环境建议

缓存机制：
- 通过app.openapi_schema属性实现单例缓存，避免重复生成开销
- 开发环境可禁用缓存实时查看文档变更

安全配置：

class Settings(BaseSettings):
    docs_enabled: bool = False

app = FastAPI(docs_url="/docs" if settings.docs_enabled else None)

通过环境变量动态控制文档访问权限

版本管理：
- 使用info.x-api-version扩展字段标注接口版本
- 配合servers配置实现多版本API共存

性能监控：

openapi_schema["paths"]["/items/"]["get"]["x-ratelimit"] = {
    "limit": 100,
    "period": "1m"
}

在OpenAPI中直接声明接口限流策略

完整实现参考：
FastAPI官方扩展OpenAPI文档
测试命令示例：
1
2
3
4
5
# 查看自定义文档
curl http://localhost:8000/openapi.json | jq .info

# 禁用文档访问
DOCS_ENABLED=false uvicorn main:app