FastAPI API 文件（OpenAPI / Swagger / ReDoc）— title、description、version 完全攻略

---

簡介

在 FastAPI 中，API 文件是自動產生的 OpenAPI（亦稱 Swagger）規格，開發者只要寫完路由，文件就會即時同步更新。
其中 title、description、version 三個屬性看似簡單，卻是使用者第一次接觸 API 時最先看到的資訊，直接影響 可讀性、專案維護 以及 第三方工具（如 Postman、ReDoc）對文件的呈現方式。

本篇文章將說明如何在 FastAPI 中正確設定這三個欄位，並提供 3‑5 個實務範例，讓你從新手快速升級為能自行客製化文件的中階開發者。

---

核心概念

1. FastAPI 的 FastAPI() 建構子

FastAPI() 接受多個參數，其中最常用的三個就是：

參數	型別	功能
title	str	API 文件的 主標題，會顯示在 Swagger UI 與 ReDoc 的最上方。
description	str	說明文字，支援 Markdown，可用來放置使用說明、授權資訊或範例。
version	str	API 版本號，通常遵守 MAJOR.MINOR.PATCH（如 1.0.0）的語意化版本規範。

這三個參數會直接寫入 OpenAPI 3.0 的 info 區塊，所有自動產生的文件皆以此為基礎。

小技巧：若專案需要多語系說明，可在 description 中使用 Markdown 的 <details> 標籤切換顯示內容。

2. 為什麼要自訂 title、description、version？

1. 提升使用者體驗
   • 好的標題與說明能讓前端或合作夥伴快速了解 API 的定位與使用方式。
2. 協助版本管理
   • 明確的版本號讓測試、部署與回溯更安全，尤其在微服務環境中尤為重要。
3. 支援自動化文件產出
   • 許多 CI/CD 流程會抓取 OpenAPI JSON，若資訊不完整會導致生成的 SDK 或測試案例失敗。

3. 自訂文件的進階方式

FastAPI 允許在應用啟動後重新生成 OpenAPI schema，這對於需要根據環境或使用者權限動態變更說明的情境相當有用。

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="My Custom API",
        version="2.1.0",
        description="這是一個 **動態產生** 的 API 文件範例。",
        routes=app.routes,
    )
    # 例如：加入全局安全定義
    openapi_schema["components"]["securitySchemes"] = {
        "BearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app = FastAPI()
app.openapi = custom_openapi

上述程式碼示範了 覆寫 app.openapi 方法，以自訂 title、description、version，同時加入額外的安全定義。

---

程式碼範例

以下提供 五個實用範例，涵蓋從最簡單的設定到進階的客製化需求。

範例 1：最基本的 title、description、version

# file: main_basic.py
from fastapi import FastAPI

app = FastAPI(
    title="圖書館管理 API",
    description="""
    此 API 提供圖書館的 **書籍 CRUD**、借閱紀錄查詢等功能。  
    - 使用 `GET /books` 取得書籍列表  
    - 使用 `POST /borrow` 送出借書請求  
    """,
    version="1.0.0",
)

@app.get("/books")
def read_books():
    """取得所有書籍"""
    return [{"id": 1, "title": "Python 入門"}]

說明：description 使用了 Markdown，Swagger UI 會自動渲染成有格式的文字。

範例 2：在說明中加入圖片與連結

# file: main_image.py
from fastapi import FastAPI

app = FastAPI(
    title="影像辨識服務",
    description="""
    ![示意圖](https://example.com/logo.png)

    本服務提供 **即時影像辨識**，支援以下模型：
    - **ResNet50**：適用於一般影像分類
    - **YOLOv5**：即時物件偵測

    更多資訊請參考 [官方文件](https://docs.example.com)。
    """,
    version="0.9.3",
)

技巧：外部圖片與超連結在 Swagger UI 與 ReDoc 都能正確顯示，提升文件的可視化效果。

範例 3：動態產生說明（根據環境變數）

# file: main_dynamic.py
import os
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

def get_description():
    env = os.getenv("ENV", "development")
    if env == "production":
        return "正式環境的 API，已啟用完整的安全機制。"
    return "開發環境，僅供測試使用。"

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="動態說明 API",
        version="2.0.0",
        description=get_description(),
        routes=app.routes,
    )
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

情境：部署到不同環境時，文件會自動顯示相對應的說明，避免手動變更。

範例 4：使用 ReDoc 替代 Swagger UI

# file: main_redoc.py
from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI(
    title="ReDoc 範例 API",
    description="使用 ReDoc 產生更美觀的 API 文件。",
    version="1.2.1",
    docs_url=None,          # 關閉預設 Swagger UI
    redoc_url="/docs",      # 改用 ReDoc
)

@app.get("/ping")
def ping():
    """簡易健康檢查"""
    return {"msg": "pong"}

提示：將 docs_url 設為 None 後，預設的 Swagger UI 會被關閉，只保留 ReDoc。兩者皆可同時開啟，只要分別設定不同的路徑。

範例 5：在文件中加入全局標籤（Tag）與說明

# file: main_tags.py
from fastapi import FastAPI, APIRouter

app = FastAPI(
    title="多模組 API",
    description="示範如何為不同模組加上 Tag，方便在 Swagger UI 中分組。",
    version="3.0.0",
)

books_router = APIRouter(prefix="/books", tags=["📚 書籍管理"])
users_router = APIRouter(prefix="/users", tags=["👤 使用者管理"])

@books_router.get("/")
def list_books():
    """取得書籍清單"""
    return [{"id": 1, "title": "FastAPI 完全攻略"}]

@users_router.post("/")
def create_user():
    """新增使用者"""
    return {"msg": "使用者已建立"}

app.include_router(books_router)
app.include_router(users_router)

好處：在 Swagger UI 中，Tag 會自動顯示為分組，讓大型專案的文件更易於瀏覽。

---

常見陷阱與最佳實踐

陷阱	可能的結果	建議的解決方式
忘記設定 description	Swagger UI 只會顯示空白說明，使用者需要自行閱讀程式碼才能了解 API 功能。	務必 為每個專案撰寫完整的 Markdown 說明，包含使用範例與授權資訊。
版本號未遵守語意化規範	CI 產生的 SDK 可能無法正確對應版本，導致升級衝突。	使用 MAJOR.MINOR.PATCH，每次功能變更或相容性破壞時相應升級。
在 description 中直接寫入 HTML	部分瀏覽器或 ReDoc 可能會過濾掉 HTML，造成排版錯亂。	優先使用 Markdown，必要時使用 <details> 包裝額外資訊。
自訂 openapi 時忘記快取	每次呼叫 /openapi.json 都會重新計算，造成效能下降。	在 custom_openapi 中加入快取（如上例 if app.openapi_schema: return app.openapi_schema）。
同時啟用 Swagger UI 與 ReDoc，路徑衝突	兩者會互相覆寫，導致其中一個無法存取。	分別設定 docs_url="/swagger"、redoc_url="/redoc"，避免衝突。

最佳實踐：

1. 在專案根目錄放置 README.md，並將其內容複製到 description，確保說明一致。
2. 使用環境變數或設定檔（如 .env）管理 version，避免手動忘記更新。
3. 在 CI 流程中自動驗證 OpenAPI JSON 是否符合規範（可使用 speccy、openapi-cli）。
4. 針對每個主要功能模組使用 Tag，讓文件在大型專案中保持清晰。
5. 定期檢查 ReDoc 與 Swagger UI 的相容性，FastAPI 版本升級後可能會有 UI 變更。

---

實際應用場景

場景	為何需要自訂 title/description/version	實作重點
內部微服務平台	多個服務共用同一入口，必須清楚標示服務名稱與版本，以免前端呼叫錯誤 API。	在每個微服務的 FastAPI() 中設定獨立的 title、version，並在 description 加入服務的服務等級協議（SLA）。
對外公開的 SaaS API	客戶開發者需要完整的使用說明與版本號，才能生成 SDK。	使用 Markdown 撰寫詳細的 description（包含授權流程、錯誤碼說明），並在部署腳本中自動更新 version。
多語系文件需求	國際客戶可能需要中文、英文說明。	在 description 中利用 <details> 包住不同語言的說明，或在 CI 中產生多個 OpenAPI 檔案（openapi.zh.json、openapi.en.json）。
API 測試自動化	測試框架（如 pytest + httpx）會根據 OpenAPI 產生測試案例，版本不符會導致測試失敗。	每次發佈新功能時，先升級 version，再跑一次 OpenAPI 生成檢查。
文件美化與品牌化	客戶期待的文件風格與企業品牌一致，包含 LOGO、配色等。	在 description 中嵌入公司 LOGO 圖片，使用 ReDoc 的 redoc_options 自訂樣式（透過 app = FastAPI(..., redoc_url="/docs", redoc_js_url="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js")）。

---

總結

• title、description、version 是 FastAPI 產生的 OpenAPI 文件最基礎且最重要的三個屬性。
• 透過簡單的建構子參數即可完成設定，亦可利用 custom_openapi 進行 進階客製化（加入安全機制、動態說明等）。
• Markdown 是撰寫說明的最佳選擇，支援圖片、連結與摺疊區塊，讓文件既美觀又易讀。
• 請遵守語意化版本規範，並在 CI/CD 中加入 OpenAPI 檢查，以確保文件的正確性與一致性。
• 最後，根據不同的 實務場景（內部微服務、對外 SaaS、品牌化文件），適時調整 title、description、version 的呈現方式，讓 API 使用者得到最佳的開發體驗。

掌握了這些技巧後，你的 FastAPI 專案不僅功能完整，連文件也能像專業產品一樣，清晰、完整且易於維護。祝開發順利！