什麼是 Swagger UI？
FastAPI 會提供 OpenAPI Schema，並內建互動式文件介面 Swagger UI，預設路徑為 /docs，可直接在瀏覽器測試 API。
Swagger UI 基礎應用
- 開啟文件頁面：啟動後預設可在 http://127.0.0.1:8000/docs 看到 Swagger UI，通常不需額外設定。
- 自訂文件資訊：在 FastAPI() 實例化時傳入 title、description、version 可修改文件標題與描述。
- 分組標籤：在路徑裝飾器加入 tags=["名稱"]，可將 API 依功能分類顯示在文件中。
- API 端點描述：可用 summary 設定簡短標題，詳細說明可以寫在Python docstring。
- 資料模型展示：透過 Pydantic 定義 response_model，讓文件自動顯示輸入與輸出的 Schema 結構。
- 停用文件：若為正式環境安全考量，可設定 redoc_url=None、docs_url=None、openapi_url=None 關閉頁面。
from fastapi import FastAPI
from pydantic import BaseModel, Field
# 1. 實例化 App 並設定文件資訊
app = FastAPI(
title="商品管理系統 API", # 文件大標題
description="Swagger UI 教學範例", # 文件副標題與描述
version="1.0.0", # API 版本號
# docs_url="/docs", # 預設是 /docs
# redoc_url="/redoc", # 預設是 /redoc
# openapi_url="/openapi.json", # 預設是 /openapi.json
)
# 定義資料模型 (Schema)
class Item(BaseModel):
name: str = Field(
...,
examples=["無線滑鼠"],
)
price: int = Field(
...,
gt=0,
examples=[599],
)
in_stock: bool = Field(
True,
)
# 2. 建立 API 路由，加入文件描述參數
@app.post("/items/", tags=["商品管理"], summary="新增商品", response_model=Item)
def create_item(item: Item):
"""
建立新商品的詳細說明：
- **name**: 商品名稱
- **price**: 商品價格 (必須大於 0)
- **in_stock**: 預設為 True
"""
print(f"收到商品: {item.name}")
return item
@app.get("/items/{item_id}", tags=["商品管理"], summary="查詢商品")
def read_item(item_id: int):
# 示範路徑參數的文件生成
return {"item_id": item_id, "name": "測試商品"}
