0%

FastAPI自学教程（87） - 条件式OpenAPI配置

发表于 2025-04-26 分类于编程

1.基础用法

from fastapi import FastAPI
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    openapi_url: str = "/openapi.json"

settings = Settings()
app = FastAPI(openapi_url=settings.openapi_url)

@app.get("/")
async def root():
    return {"message": "Hello World"}

通过Pydantic设置模型定义openapi_url配置项，默认值为/openapi.json
在FastAPI实例化时注入配置，动态控制OpenAPI文档生成路径

流程说明：

graph TD
  A[环境变量配置] --> B{OPENAPI_URL值}
  B -->|空字符串| C[禁用文档生成]
  B -->|有效路径| D[生成标准文档]
  C --> E[访问文档返回404]
  D --> F[正常显示交互文档]

2.生产环境配置

2.1 禁用文档方法

1	OPENAPI_URL= uvicorn main:app

设置环境变量OPENAPI_URL为空字符串时，自动禁用以下端点：
- /openapi.json
- /docs（Swagger UI）
- /redoc（ReDoc）

2.2 安全注意事项

非安全措施：禁用文档无法替代真正的API安全防护
推荐安全实践：
- 使用Pydantic模型严格验证请求/响应数据
- 实现基于角色的访问控制（RBAC）
- 配置HTTPS加密传输
- 使用JWT令牌认证机制

3.扩展应用场景

3.1 多环境配置

1
2
3

class Settings(BaseSettings):
    env_name: str = "dev"
    openapi_url: str = "/openapi.json" if env_name == "dev" else ""

根据env_name环境变量动态切换文档可见性
开发环境保留文档，生产环境禁用

3.2 自定义文档路径

1	OPENAPI_URL=/internal/docs.json uvicorn main:app

通过环境变量修改OpenAPI规范文件路径
配合Nginx白名单实现内部文档访问控制

完整实现参考：
FastAPI官方文档 - 条件式OpenAPI配置
测试命令示例：
1
2
3
4
5
# 禁用文档模式
OPENAPI_URL= uvicorn main:app --port 8000

# 验证文档不可访问
curl http://localhost:8000/docs