条件化 OpenAPI¶

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

关于安全、API 和文档¶

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

这并不会为您的 API 增加任何额外的安全性，*路径操作*仍然可以在它们所在的地方访问。

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

隐藏文档只会增加理解如何与您的 API 交互的难度，并且可能会增加您在生产环境中调试它的难度。这可以被视为一种隐匿安全。

如果您想保护您的 API，您可以做一些更好的事情，例如

确保您为请求体和响应定义了良好的 Pydantic 模型。
使用依赖项配置任何必需的权限和角色。
切勿存储明文密码，只存储密码哈希。
实现并使用众所周知的加密工具，例如 pwdlib 和 JWT 令牌等。
在需要时添加更精细的权限控制，例如 OAuth2 范围。
...等等。

尽管如此，您可能有一个非常具体的使用场景，您确实需要为某些环境（例如生产环境）禁用 API 文档，或者根据环境变量的配置来禁用。

从设置和环境变量中条件化 OpenAPI¶

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

例如

Python 3.9+

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