FastAPI 条件化 OpenAPI：用 Pydantic 设置与环境变量控制（甚至完全禁用）OpenAPI 及文档界面

本篇指南基于 FastAPI 官方文档中的「Conditional OpenAPI」一节展开：教你如何用 pydantic_settings 的 Settings 类读取环境变量，把 openapi_url 等配置项做成可随部署环境切换的条件配置，并演示如何在生产环境通过一个环境变量就完全关闭 OpenAPI Schema 与 /docs、/redoc 界面。读完你可以掌握“同一份代码、多套环境行为”的标准做法，并能从源码层面理解 openapi_url 为空时文档路由为何会整体消失。

一、先澄清：隐藏文档界面不等于 API 安全

在写任何配置之前，官方文档首先强调了一个安全原则：在生产环境隐藏文档界面（Swagger UI / ReDoc / OpenAPI JSON）不应该作为保护 API 的手段。

理由如下：

• 隐藏文档不会给 API 增加任何额外安全层，你的*路径操作（path operations）*依然挂载在原来的 URL 上，客户端照样可以访问；
• 如果代码本身存在安全漏洞，隐藏文档后它依然存在；
• 隐藏文档只会让别人更难理解如何与你的 API 交互，也可能让你在生产环境排障时更难调试；
• 官方将其定性为一种「Security through obscurity（靠隐匿获得安全）」的做法。

如果想真正保护 API，文档建议采用以下更有效的措施：

措施	说明
良好的 Pydantic 模型	为请求体（request bodies）和响应（responses）定义严格的数据模型，靠类型与校验拒绝非法输入
用依赖注入管理权限	通过 Depends 配置所需的权限和角色
不存明文密码	永远只存储密码哈希
使用成熟密码学工具	如 pwdlib、JWT tokens 等业界标准组件
OAuth2 Scopes 细粒度控制	在需要更细粒度授权的地方引入 scope 控制
等等	…

但不可否认，确实存在一类特定场景：你需要针对某个具体环境（例如生产）或根据环境变量中的配置，把 API 文档真正关掉。这正是本节要解决的实际需求。

二、用 Pydantic Settings + 环境变量条件化配置 OpenAPI

FastAPI 的自动 OpenAPI 与文档界面（/openapi.json、/docs、/redoc）由创建 FastAPI 应用时传入的一批参数控制，其中最关键的是 openapi_url——它决定了 OpenAPI Schema 的发布地址，同时也是 /docs 与 /redoc 是否注册的总开关（这一点后面会从源码印证）。

仓库中的示例代码 docs_src/conditional_openapi/tutorial001_py310.py 展示了完整做法：

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("/")
def root():
    return {"message": "Hello World"}

逐行解读：

1. class Settings(BaseSettings)：pydantic_settings.BaseSettings 会为每个字段自动匹配同名大写环境变量（字段 openapi_url 对应环境变量 OPENAPI_URL）。
2. openapi_url: str = "/openapi.json"：声明设置项 openapi_url，默认值就是 FastAPI 自身的默认值 "/openapi.json"，所以本地开发时不设置任何环境变量，行为与 FastAPI() 完全一致。
3. settings = Settings()：实例化时读取环境变量；若环境存在 OPENAPI_URL，其值将覆盖默认值。
4. app = FastAPI(openapi_url=settings.openapi_url)：把配置结果传给应用构造器。注意这个值在 import 模块时就被求值，因此在进程启动前设置环境变量才能生效。

对应 fastapi/applications.py 中 openapi_url 参数的官方定义，类型是 str | None，默认 "/openapi.json"，文档说明里明确写道：

The URL where the OpenAPI schema will be served from. If you set it to None, no OpenAPI schema will be served publicly, and the default automatic endpoints /docs and /redoc will also be disabled.

即：设为 None 时，不公开任何 OpenAPI Schema，且 /docs、/redoc 一并禁用。本教程用空字符串 "" 达到同样效果——因为 fastapi/applications.py 中的判断是 if self.openapi_url:，空字符串与 None 一样是假值，都会走“不注册文档路由”的分支。

三、通过环境变量 OPENAPI_URL 完全禁用 OpenAPI

要禁用 OpenAPI（连同文档界面），只需把环境变量 OPENAPI_URL 设为空字符串再启动服务：

$ OPENAPI_URL= uvicorn main:app

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

此时访问 /openapi.json、/docs、/redoc 三个地址，得到的都只是 404 Not Found：

{
    "detail": "Not Found"
}

而业务路由（如 /）完全不受影响。这一行为已被仓库中的测试用例逐条断言验证，见 tests/test_tutorial/test_conditional_openapi/test_tutorial001.py：

def test_disable_openapi(monkeypatch):
    monkeypatch.setenv("OPENAPI_URL", "")
    # Load the client after setting the env var
    client = get_client()
    response = client.get("/openapi.json")
    assert response.status_code == 404, response.text
    response = client.get("/docs")
    assert response.status_code == 404, response.text
    response = client.get("/redoc")
    assert response.status_code == 404, response.text

同一个测试文件里还有两个对照组：test_default_openapi 验证不设环境变量时 /docs、/redoc 返回 200 且 /openapi.json 输出完整 OpenAPI 3.1.0 Schema；test_root 验证业务路由始终可用。也就是说，“空串禁用”与“默认启用”两条路径都有自动化测试兜底。

四、源码印证：为什么 openapi_url 为空时文档界面整体消失

从源码结构看，文档相关路由并不是分别独立开关的，而是全部挂在 openapi_url 这一个条件后面。fastapi/applications.py 的 setup() 方法中：

def setup(self) -> None:
    if self.openapi_url:
        async def openapi(req: Request) -> JSONResponse:
            ...
            return JSONResponse(schema)

        self.add_route(self.openapi_url, openapi, include_in_schema=False)
    if self.openapi_url and self.docs_url:
        async def swagger_ui_html(req: Request) -> HTMLResponse:
            ...
        self.add_route(self.docs_url, swagger_ui_html, include_in_schema=False)
        ...
    if self.openapi_url and self.redoc_url:
        async def redoc_html(req: Request) -> HTMLResponse:
            ...
        self.add_route(self.redoc_url, redoc_html, include_in_schema=False)

三个 add_route 分别对应 /openapi.json（Swagger UI 页面模板中的 openapi_url 变量，见 fastapi/openapi/docs.py）、/docs、/redoc，而每个分支都先判断 self.openapi_url。因此：

• openapi_url=""（本教程方案）或 openapi_url=None（API 直接指定的方案）：三个路由都不会注册，请求自然落到 404；
• 若你只想改地址而不禁用，例如 app = FastAPI(openapi_url="/api/v1/openapi.json")，/docs 与 /redoc 会自动指向新地址——因为 swagger_ui_html / redoc_html 内部用 root_path + self.openapi_url 拼接真实的 schema 地址。

另外值得注意的是 fastapi/applications.py 中的一组断言：

if self.openapi_url:
    assert self.title, "A title must be provided for OpenAPI, e.g.: 'My API'"
    assert self.version, "A version must be provided for OpenAPI, e.g.: '2.1.0'"

只有启用了 OpenAPI（openapi_url 为真值）时，才强制要求提供 title 和 version——这也与「禁用 OpenAPI 时可以不带任何 OpenAPI 元信息」的设计意图一致。

五、小结与适用前提

• 该方案的核心是：把 openapi_url 放进 BaseSettings，让部署系统通过环境变量 OPENAPI_URL 在运行时决定文档开/关/换址，代码本身零改动；
• 适用前提：环境变量必须在进程启动（模块 import）之前设置好；空字符串与 None 在“禁用”语义上等价，但直接写 None 需要代码改动，而空串可由部署环境注入，这正是文档推荐环境变量的原因；
• 再强调一次文档的安全立场：禁用文档只解决「某个环境不对外展示文档」的运营需求，绝不能替代 Pydantic 校验、依赖注入鉴权、密码哈希、OAuth2 scopes 等真正的安全机制；
• 相关参考路径：示例源码 docs_src/conditional_openapi/tutorial001_py310.py、应用主类 fastapi/applications.py、Swagger UI 页面模板 fastapi/openapi/docs.py、测试 tests/test_tutorial/test_conditional_openapi/test_tutorial001.py。