include_in_schema=False 是最轻量的单接口隐藏方式，仅从 OpenAPI 描述中排除该路径，不影响实际调用；必须作为 @app.get 等装饰器参数传入，不可置于函数体内或中间件中。
用 include_in_schema=False 排除单个接口
这是最直接、最轻量的方式，适用于个别需要隐藏的管理接口、健康检查或内部调试路由。它不会影响接口实际运行，只是让 FastAPI 在生成 /openapi.json 时跳过该路径操作。
常见错误现象：设了 include_in_schema=False 后仍能在 /docs 中看到接口——大概率是没加在正确的装饰器参数里，或误加在了函数体内部。
- 必须作为路径操作装饰器（如
@app.get）的参数传入，不是函数返回值或中间件逻辑 - 对
HTTPException响应、重定向等无影响，仅控制 OpenAPI 描述是否生成 - 不提供任何访问控制，接口仍可通过原始 URL 调用（需额外加权限校验）
示例：
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
@app.get("/admin/backup", include_in_schema=False)
async def trigger_backup():
return {"status": "started"}
用环境变量开关全局文档入口
生产环境禁用整个文档页面是最稳妥的底线方案，尤其当团队没有统一鉴权能力或文档中混有大量未清理的内部接口时。
使用场景：CI/CD 部署到生产环境后自动关闭 /docs 和 /redoc，开发环境保持开启。
- 设置
docs_url=None和redoc_url=None即可彻底移除两个入口 - 注意：这也会让
/openapi.json不再暴露（除非显式配置openapi_url） - 若需保留
/openapi.json供 CI 工具消费，但隐藏 UI，可只设docs_url=None，保留redoc_url="/redoc"再配合中间件限制
示例：
import os
from fastapi import FastAPI
docs_enabled = os.getenv("ENABLE_DOCS", "false").lower() == "true"
app = FastAPI(
docs_url="/docs" if docs_enabled else None,
redoc_url="/redoc" if docs_enabled else None,
)
用中间件拦截文档请求路径
当你需要动态控制访问权限（比如只允许内网 IP 或特定 Header），而不是简单开关，中间件是更灵活的选择。
容易踩的坑：中间件顺序错位导致未生效；或拦截了 /openapi.json 导致 UI 无法加载（ReDoc/Swagger 依赖它）。
- 只拦截
/docs、/redoc、/docs/oauth2-redirect等 HTML/JS 资源路径，不要拦/openapi.json - 返回
403比404更安全——避免暴露“此处有文档”的线索 - 若用 Nginx 做前置，建议优先在反代层做 IP 白名单，减少 Python 层负担
示例（基础 IP 限制）：
@app.middleware("http")
async def block_docs_by_ip(request: Request, call_next):
client_ip = request.client.host
allowed_ips = {"127.0.0.1", "10.0.0.0/8"}
path = request.url.path
if path in ["/docs", "/redoc", "/docs/oauth2-redirect"] and client_ip not in allowed_ips:
return JSONResponse({"detail": "Access denied"}, status_code=403)
return await call_next(request)
为什么不能只靠改 URL 路径来“隐藏”文档
把 /docs 改成 /a1b2c3-docs 这类做法，在安全上毫无意义。工具扫描、日志泄露、协作误传都会让这个路径重新暴露。
真正关键的判断点在于：你是否信任所有能访问服务网络的人？如果答案是否定的，那必须叠加至少一层校验——要么是环境级开关，要么是中间件鉴权，要么是反向代理层的访问控制。
最容易被忽略的是：include_in_schema=False 只影响 OpenAPI 描述，不影响接口本身；而中间件拦截只影响 UI 访问，不影响 /openapi.json 的可读性。两者常需组合使用，才能兼顾开发便利与生产安全。
