條件式 OpenAPI¶

🌐 AI 與人類共同完成的翻譯

此翻譯由人類指導的 AI 完成。🤝

可能會有對原意的誤解，或讀起來不自然等問題。🤖

你可以透過協助我們更好地引導 AI LLM來改進此翻譯。

英文版

如果需要，你可以用設定與環境變數，依據執行環境有條件地調整 OpenAPI，甚至完全停用它。

關於安全性、API 與文件¶

在正式環境中隱藏文件 UI 不應該 是用來保護 API 的方式。

這並不會為你的 API 增添任何額外的安全性，路徑操作 仍舊照常可用。

若你的程式碼有安全性缺陷，它依然會存在。

隱藏文件只會讓他人更難理解如何與你的 API 互動，也可能讓你在正式環境除錯更困難。這通常僅被視為一種以隱匿求安全。

如果你想保護 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，會看到如下的 404 Not Found 錯誤：

{
    "detail": "Not Found"
}