条件式 OpenAPI¶

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

关于安全性、API 和文档¶

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

这不会对 API 添加任何额外的安全性，路径操作仍然可以在它们所在的位置使用。

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

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

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

确保为请求主体和响应定义了清晰的 Pydantic 模型。
使用依赖项配置任何必需的权限和角色。
不要存储纯文本密码，只存储密码哈希。
实施和使用众所周知的加密工具，例如 Passlib 和 JWT 令牌等。
根据需要添加更细粒度的权限控制，使用 OAuth2 范围。
...等等。

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

来自设置和环境变量的条件式 OpenAPI¶

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

例如

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