条件式 OpenAPI¶

如果需要，你可以使用设置和环境变量来根据环境有条件地配置 OpenAPI，甚至完全禁用它。

关于安全性、API 和文档¶

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

这并不能为你的 API 增加任何额外的安全性，路径操作仍将在它们所在的位置可用。

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

隐藏文档只会使理解如何与你的 API 交互变得更加困难，并可能使你在生产环境中调试它变得更加困难。这可以简单地被认为是通过模糊化实现安全的一种形式。

如果你想保护你的 API，有几种更好的方法可以做到，例如：

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

尽管如此，你可能有一个非常特殊的用例，需要为某些环境（例如生产环境）或根据环境变量的配置禁用 API 文档。

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

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

例如：

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 running on http://127.0.0.1:8000 (Press CTRL+C to quit)

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

{
    "detail": "Not Found"
}