条件性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"
}