FastAPI 基礎概念：為何型別提示能驅動自動文件

---

簡介

在現代 Web API 開發中，自動產生文件（Auto‑Documentation）已成為提升開發效率與維護品質的關鍵特性。FastAPI 之所以能在短短幾行程式碼內即產出完整且互動式的 Swagger UI、ReDoc，核心祕密就在於 Python 的型別提示（type hints）。

型別提示不只是 IDE 補全或靜態檢查的工具，它在 FastAPI 裡被當作 宣告式的 API 規格。框架會在啟動時讀取這些註解，結合 Pydantic 資料模型，自動產生 OpenAPI（也就是 Swagger）規格，最終呈現在文件頁面上。了解這個機制，能讓你在撰寫程式時同時完成 API 規格、驗證與文件，省下大量手動維護的時間。

本篇文章將從 型別提示的基本概念、FastAPI 如何解析、實作範例，一路說明為什麼型別提示是自動文件的驅動力，並提供常見陷阱與最佳實踐，幫助你在專案中即時享受「寫程式、產文件、驗證」三位一體的開發體驗。

---

核心概念

1. 型別提示是「宣告式」的 API 規格

在傳統的 Flask、Django REST Framework 等框架中，開發者必須自行撰寫 Swagger / OpenAPI JSON，或使用額外套件產生。FastAPI 則把 函式簽名 當作 API 規格的來源：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    """
    透過型別提示告訴 FastAPI:
    - item_id 必須是 int
    - q 為可選的字串
    """
    return {"item_id": item_id, "q": q}

• item_id: int → FastAPI 會在 OpenAPI 中將此參數標記為 path parameter，型別為 integer。
• q: str | None = None → 被視為 query parameter，而 None 表示此參數是 可選。

只要寫對型別，框架就能自動產生對應的文件與驗證邏輯。

2. Pydantic 模型：結合型別與驗證

FastAPI 內建 Pydantic 作為資料模型的基礎。Pydantic 以 type hints 定義欄位，同時提供 資料驗證、序列化、文件說明。

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(..., description="商品名稱")
    price: float = Field(..., gt=0, description="商品價格，必須大於 0")
    tags: list[str] | None = Field(default=None, description="商品標籤")

在路由中直接使用 Item，FastAPI 會：

1. 讀取模型的型別與 Field 的額外資訊，產生 OpenAPI schema。
2. 在請求到達時，利用 Pydantic 執行 自動驗證，若失敗則回傳 422 錯誤。

3. 依賴注入（Dependency Injection）與型別提示

FastAPI 的依賴系統同樣依賴型別提示。只要在函式參數加上 Depends，框架會根據返回值的型別自動產生文件說明。

from fastapi import Depends, Header

def get_token(x_token: str = Header(...)):
    return x_token

@app.get("/protected")
def protected_route(token: str = Depends(get_token)):
    return {"token": token}

這裡 x_token 被標記為 header，而 protected_route 的 token 參數會在文件中顯示為 依賴，說明必須提供 x-token Header。

4. 回傳型別提示：產生 Response Model

FastAPI 會根據 回傳值的型別 產生 response model，讓文件清楚描述成功回傳的結構。

@app.post("/items", response_model=Item)
def create_item(item: Item):
    # 假裝寫入資料庫...
    return item

即使開發者在程式碼中直接回傳 Item 實例，文件仍會顯示 Item 的 JSON schema，且自動加入 200 OK 的說明。

---

程式碼範例

以下提供 5 個實用範例，展示如何利用型別提示完成自動文件、驗證與依賴注入。

範例 1：基本路由與 Query Parameter

from fastapi import FastAPI

app = FastAPI()

@app.get("/search")
def search(q: str, limit: int = 10):
    """
    *q* 為必填的搜尋關鍵字，*limit* 為回傳筆數上限，預設 10。
    """
    # 假資料
    results = [{"id": i, "title": f"{q} result {i}"} for i in range(limit)]
    return {"query": q, "results": results}

說明：q: str 產生 query parameter，limit: int = 10 產生可選參數且在文件中顯示預設值 10。

範例 2：使用 Pydantic 建立 Request Body

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr, Field

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, description="使用者帳號")
    email: EmailStr = Field(..., description="有效的 Email")
    password: str = Field(..., min_length=6, description="密碼，最少 6 個字元")

app = FastAPI()

@app.post("/users", response_model=UserCreate)
def create_user(user: UserCreate):
    """
    建立新使用者，所有欄位皆必填。
    """
    # 假裝寫入 DB
    return user

說明：EmailStr 讓 FastAPI 在文件中顯示 format: email，而 Field 的描述會直接寫入 Swagger UI。

範例 3：Path Parameter 與 Enum

from fastapi import FastAPI
from enum import Enum

class Status(str, Enum):
    active = "active"
    inactive = "inactive"
    banned = "banned"

app = FastAPI()

@app.get("/users/{user_id}/status/{status}")
def set_status(user_id: int, status: Status):
    """
    變更使用者狀態，*status* 只能是 Enum 中的值。
    """
    return {"user_id": user_id, "new_status": status}

說明：Enum 會被轉換成 string enum，文件中會自動產生下拉選單供測試使用。

範例 4：依賴注入與 Header 驗證

from fastapi import FastAPI, Depends, Header, HTTPException, status

app = FastAPI()

def verify_api_key(x_api_key: str = Header(...)):
    if x_api_key != "secret-key":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid API Key"
        )
    return x_api_key

@app.get("/secure-data")
def secure_endpoint(api_key: str = Depends(verify_api_key)):
    """
    只有提供正確的 *x-api-key* Header 才能存取。
    """
    return {"message": "You have access!", "api_key": api_key}

說明：Depends 讓 FastAPI 在文件中標示此路由需要 x-api-key Header，且自動加入 401 回應說明。

範例 5：回傳模型與自訂 Response Code

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel

class Product(BaseModel):
    id: int
    name: str
    price: float

fake_db = {1: {"id": 1, "name": "筆記型電腦", "price": 29999.99}}

app = FastAPI()

@app.get(
    "/products/{product_id}",
    response_model=Product,
    responses={404: {"description": "找不到商品"}}
)
def get_product(product_id: int):
    """
    取得單一商品資訊，若不存在回傳 404。
    """
    product = fake_db.get(product_id)
    if not product:
        raise HTTPException(status_code=404, detail="商品不存在")
    return product

說明：response_model 指定回傳結構，responses 讓文件顯示自訂的 404 說明。

---

常見陷阱與最佳實踐

陷阱	可能的後果	解決方式 / 最佳實踐
忘記在路由函式加入型別提示	文件缺少參數說明，且 FastAPI 不會自動驗證，導致 500 錯誤或未預期行為。	必須 為每個參數（path、query、body、header）加上明確的型別或 Depends。
使用 Any 或過寬的型別	OpenAPI 會產生 type: object，失去結構化文件的優勢。	盡量使用具體型別或自訂 Pydantic 模型；若真的需要 Any，在 Field 中補充 description。
Pydantic 欄位缺少 Field(..., description=…)	Swagger UI 中欄位說明空白，使用者不易了解需求。	為每個模型欄位加上 description、example、gt/lt 等限制，讓文件更完整。
Enum 未繼承 str	產生的 OpenAPI schema 為 integer（預設 enum 為 int），前端可能無法正確對應字串。	Enum 必須繼承 str（例如 class Status(str, Enum):），保證產出 string enum。
回傳型別與實際回傳不一致	文件顯示錯誤結構，測試工具（如 Swagger UI）會顯示驗證失敗。	確保 response_model 與實際回傳的資料結構一致，或使用 response_model_exclude_unset=True 等參數調整。
依賴函式缺少型別提示	依賴的參數不會出現在文件，使用者不曉得必須提供哪些 Header/Query。	在依賴函式的參數上同樣加上型別與 Header、Query 等宣告。

最佳實踐總結

1. 每個參數都寫型別：即使是 int | None 也要明確標示。
2. 使用 Pydantic Field 補足說明：description、example、gt/lt 能讓文件自動生成範例。
3. Enum 必須繼承 str：保證前端得到字串枚舉。
4. 回傳模型（response_model）保持同步：避免文件與實際 API 不一致。
5. 善用 responses 追加非 200 的說明：讓使用者了解所有可能的錯誤碼。

---

實際應用場景

1. 內部微服務間的契約文件

在微服務架構中，各服務之間的 API 合約必須保持同步。透過 FastAPI 的型別提示，開發者只要更新 Pydantic 模型或路由簽名，即可自動產生最新的 OpenAPI 規格，供 CI/CD 流程自動驗證（例如使用 spectral 或 swagger-cli）。

2. 前端與測試團隊的協作

前端開發者可以直接在 Swagger UI 中看到完整的請求參數、範例值與回傳結構，甚至可以直接點擊「Try it out」測試 API。測試工程師則能以產出的 openapi.json 為基礎，使用 pytest + httpx 撰寫自動化測試，保證前後端行為一致。

3. 產生 API 客戶端 SDK

許多團隊會利用 openapi-generator 或 swagger-codegen 從 FastAPI 產出的 OpenAPI 文件自動產生多語言 SDK（如 TypeScript、Java、Go）。只要型別提示正確，生成的 SDK 會擁有完整的型別定義，減少手動編寫與錯誤。

4. 動態文件與版本控制

FastAPI 允許同一個應用同時掛載多個路由版本（如 /v1, /v2），每個版本的型別提示會產出獨立的文件，方便在 Git 中追蹤 API 變更歷史。

---

總結

型別提示是 FastAPI 自動文件的核心驅動力。透過在函式簽名、Pydantic 模型、依賴注入等處明確宣告資料型別，框架能即時生成符合 OpenAPI 標準的規格文件，並在請求階段自動執行資料驗證。

• 寫一次型別提示，得到三件事：自動文件、資料驗證、型別安全。
• 善用 Field、Enum、response_model，讓文件更具可讀性與可測試性。
• 避免常見陷阱（忘寫型別、過寬的 Any、Enum 類型不正確），即可最大化 FastAPI 的開發效益。

掌握了這套「型別提示 → OpenAPI → Swagger」的循環，你不僅能快速打造乾淨、文件完整的 RESTful API，還能在團隊協作、微服務治理與自動化測試上獲得顯著的生產力提升。快把這些概念落實到你的下一個 FastAPI 專案，體驗「寫程式、產文件、驗證」同時進行的極致開發快感吧！