按条件配置 OpenAPI¶

🌐 由 AI 与人类协作翻译

本翻译由人类引导的 AI 生成。🤝

可能存在误解原意或不够自然等问题。🤖

你可以通过帮助我们更好地引导 AI LLM来改进此翻译。

英文版本

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

关于安全、API 和文档¶

在生产环境隐藏文档界面并不应该成为保护 API 的方式。

这并不会给你的 API 增加任何额外的安全性，路径操作 仍然会在原来的位置可用。

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

隐藏文档只会让理解如何与 API 交互变得更困难，也可能让你在生产环境中调试更困难。这大体上可以被视为一种通过隐藏实现安全的做法。

如果你想保护你的 API，有很多更好的措施，例如：

确保为请求体和响应定义完善的 Pydantic 模型。
使用依赖配置所需的权限和角色。
绝不要存储明文密码，只存储密码哈希。
实现并使用成熟的密码学工具，比如 pwdlib 和 JWT 令牌等。
在需要的地方使用 OAuth2 作用域添加更细粒度的权限控制。
...等。

尽管如此，你可能确实有非常特定的用例，需要在某些环境（例如生产环境）禁用 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，就会得到一个 404 Not Found 错误，例如：

{
    "detail": "Not Found"
}