FastAPI怎么在文档中隐藏特定的敏感API接口-Python教程-PHP中文网

include_in_schema=false 是最轻量的单接口隐藏方式，仅从 openapi 描述中排除该路径，不影响实际调用；必须作为 @app.get 等装饰器参数传入，不可置于函数体内或中间件中。

fastapi怎么在文档中隐藏特定的敏感api接口

用 `include_in_schema=False` 排除单个接口

这是最直接、最轻量的方式，适用于个别需要隐藏的管理接口、健康检查或内部调试路由。它不会影响接口实际运行，只是让 FastAPI 在生成 /openapi.json 时跳过该路径操作。

常见错误现象：设了 include_in_schema=False 后仍能在 /docs 中看到接口——大概率是没加在正确的装饰器参数里，或误加在了函数体内部。

必须作为路径操作装饰器（如 @app.get）的参数传入，不是函数返回值或中间件逻辑
对 HTTPException 响应、重定向等无影响，仅控制 OpenAPI 描述是否生成
不提供任何访问控制，接口仍可通过原始 URL 调用（需额外加权限校验）

示例：

FastAPI Flask Proxy

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)