配置 OpenAPI¶

使用设置与环境变量基于环境实现按条件配置 OpenAPI，甚至完全禁用 OpenAPI。

关于安全、API 与文档¶

在生产环境下隐藏文档用户界面并不能妥善保护 API。

这种方式不会让 API 更安全，而且路径操作依然有效。

如果代码中存在安全隐患，这些隐患仍然存在。

隐藏文档只是让与 API 的交互变得更难，也让在生产环境下的调试变得更难。这种方式只是隐式安全（Security through obscurity）的简单形式。

以下几种方式能更好地保证 API 的安全：

确保要好好定义请求体与响应的 Pydantic 模型
使用依赖项配置所需的权限与角色
永远不要保存明文密码，只保存哈希过的密码
使用知名的加密工具，如 Passlib 或 JWT Token 等
在必要时，使用 OAuth2 作用域添加更多精细权限控制
等……

尽管如此，您还可能会遇到极个别的用例，要在某些环境（如生产环境）下禁用 API 文档，或根据环境变量配置 OpenAPI。

使用设置与环境变量按条件配置 OpenAPI¶

使用 Pydantic 设置可以轻松地配置 OpenAPI 与 API 文档。

例如：

from fastapi import FastAPI
from pydantic 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.json 设置为 openapi_url 的默认值。

并在创建 FastAPI 应用时使用 openapi_url。

把环境变量 OPENAPI_URL 设置为空字符串，就可以禁用 OpenAPI（包括 API 文档），如下所示：

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