条件化 OpenAPI¶

如有需要，你可以通过设置和环境变量根据运行环境条件化地配置 OpenAPI，甚至完全禁用它。

关于安全、API 和文档¶

在生产环境中隐藏文档用户界面不应该是保护 API 的方式。

这并不会为你的 API 增加任何额外的安全性，路径操作仍然会在原有位置保持可用。

如果代码中存在安全漏洞，它依然会存在。

隐藏文档只会增加理解如何与你的 API 交互的难度，并可能使你在生产环境中调试更加困难。这只能被视为一种形式的通过隐匿实现安全。

如果你想要保护 API 的安全，有几种更好的方法，例如：

确保为请求体和响应正确定义了 Pydantic 模型。
使用依赖项配置任何所需的权限和角色。
绝不存储明文密码，只存储密码哈希值。
实现并使用知名的加密工具，如 Passlib 和 JWT 令牌等。
在需要时使用 OAuth2 作用域添加更细粒度的权限控制。
……等等。

不过，你可能会有非常特定的用例，确实需要为某些环境（例如生产环境）或根据环境变量的配置禁用 API 文档。

通过设置和环境变量实现条件化 OpenAPI¶

你可以轻松使用相同的 Pydantic 设置来配置生成的 OpenAPI 和文档界面。

例如：

Python 3.8+

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"}

这里我们声明了设置 openapi_url，其默认值同样为 "/openapi.json"。

然后我们在创建 FastAPI 应用时使用它。

接着你可以通过将环境变量 OPENAPI_URL 设置为空字符串来禁用 OpenAPI（包括 UI 文档），例如：

$ OPENAPI_URL= uvicorn main:app

<span style="color: green;">INFO</span>:     Uvicorn 运行在 http://127.0.0.1:8000 (按 CTRL+C 退出)

然后如果你访问 /openapi.json、/docs 或 /redoc 这些 URL，只会收到一个 404 Not Found 错误，例如：

{
    "detail": "Not Found"
}