条件化 OpenAPI¶

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

关于安全性、API 和文档¶

在生产环境中隐藏文档用户界面不应成为保护 API 的手段。

这并不能为您的 API 增加任何额外的安全性，路径操作 (path operations) 依然可以在原有的位置被访问。

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

隐藏文档只会让用户更难理解如何与您的 API 进行交互，也可能让您在生产环境中调试时变得更加困难。这通常被认为仅仅是一种隐蔽式安全性 (Security through obscurity)。

如果您想保护您的 API，可以采取一些更好的措施，例如：

确保为您请求体和响应定义了良好的 Pydantic 模型。
使用依赖项配置所需的权限和角色。
永远不要存储明文密码，只存储密码哈希值。
实现并使用成熟的加密工具，如 pwdlib 和 JWT 令牌等。
根据需要添加更细粒度的 OAuth2 范围 (scopes) 权限控制。
...等等。

尽管如此，您可能仍有非常特殊的用例，确实需要在某些环境（例如生产环境）中或根据环境变量的配置禁用 API 文档。

根据设置和环境变量实现条件化 OpenAPI¶

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

例如

Python 3.10+

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