在開發API時，自動生成的交互式文檔是必不可少的工具。它能幫助開發者和使用者快速瞭解接口的功能、參數和返回值，甚至直接在瀏覽器中測試接口。FastAPI框架內置了強大的文檔自動生成功能，基於Swagger UI和OpenAPI規範，讓文檔編寫變得簡單高效。
爲什麼需要自動生成文檔？¶
想象一下，如果你的API沒有文檔，開發者需要手動查閱代碼才能知道接口如何調用；如果接口參數複雜，用戶可能會因不清楚格式而報錯。而FastAPI的自動文檔不僅能清晰展示接口結構，還支持交互式測試，大大降低了API的使用門檻。
Swagger UI與OpenAPI是什麼關係？¶
- OpenAPI：是一種規範，定義了API的結構和交互方式，用JSON格式描述接口的路徑、參數、響應等信息。FastAPI生成的文檔本質上就是符合OpenAPI規範的JSON文件。
- Swagger UI：是一個基於OpenAPI規範的交互式文檔工具，它會解析FastAPI生成的OpenAPI JSON文件，以可視化方式展示API文檔，並提供“Try it out”功能直接測試接口。
- ReDoc：另一個基於OpenAPI的文檔工具，與Swagger UI類似，但界面更簡潔，適合需要更結構化文檔的場景。FastAPI同樣支持，訪問
/redoc即可查看。
如何在FastAPI中啓用文檔？¶
創建一個最簡單的FastAPI應用，運行後就能自動生成文檔。以下是示例代碼：
from fastapi import FastAPI
# 創建應用實例，可通過參數設置文檔基本信息
app = FastAPI(
title="快速API示例",
description="這是一個使用FastAPI自動生成文檔的演示",
version="1.0.0"
)
@app.get("/")
def read_root():
return {"message": "Hello World"}
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}
運行應用：uvicorn main:app --reload，然後訪問：
- Swagger UI：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc
此時你會看到自動生成的文檔，包含標題、描述、接口列表和參數說明。
實用技巧：讓文檔更清晰易用¶
1. 自定義文檔基本信息¶
通過FastAPI構造函數的參數，可以設置文檔的全局信息：
app = FastAPI(
title="電商API", # 文檔標題
description="這是一個管理商品和訂單的API接口，支持用戶查詢、下單等功能",
version="1.0.0", # 版本號
terms_of_service="https://example.com/terms", # 服務條款鏈接
contact={"name": "開發團隊", "email": "dev@example.com"} # 聯繫人信息
)
2. 詳細描述接口和參數¶
接口的描述、參數說明可以通過三種方式添加：
- 函數Docstring：直接在函數內寫註釋，FastAPI會自動解析到文檔中。
- 參數裝飾器：使用Path、Query等工具類添加參數描述。
- 接口裝飾器：用description、summary、tags等參數。
示例：
from fastapi import Path, Query
@app.get("/items/{item_id}",
tags=["商品查詢"], # 按標籤分類，方便篩選
summary="查詢商品詳情", # 接口簡短描述
description="根據商品ID查詢詳細信息<br/>- **item_id** 必須爲整數<br/>- 支持返回商品庫存狀態")
def read_item(
item_id: int = Path(...,
title="商品ID",
description="商品的唯一標識（1-1000）",
ge=1, le=1000), # ge=1表示大於等於1
q: str = Query(None,
title="搜索關鍵詞",
description="可選，用於模糊匹配商品名稱")
):
return {"item_id": item_id, "q": q}
3. 隱藏不需要公開的接口¶
如果某些接口僅內部使用（如調試接口），可以通過include_in_schema=False隱藏：
@app.get("/internal/debug", include_in_schema=False) # 隱藏該接口
def internal_debug():
return {"debug": "This is internal only"}
4. 用響應模型規範返回格式¶
使用Pydantic模型定義接口返回數據，文檔會自動生成示例和參數結構：
from pydantic import BaseModel
class ItemResponse(BaseModel):
name: str
price: float
stock: int = 0 # 默認值
@app.get("/items/{item_id}", response_model=ItemResponse)
def read_item(item_id: int):
return {"name": "手機", "price": 2999.99, "stock": 100}
5. 顯示錯誤信息¶
通過HTTPException定義接口可能的錯誤狀態碼，文檔會自動標註：
from fastapi import HTTPException
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id > 100:
raise HTTPException(
status_code=400,
detail="商品ID不能超過100"
)
return {"item_id": item_id}
總結¶
FastAPI的自動文檔功能基於OpenAPI規範，通過Swagger UI和ReDoc提供直觀的接口展示。掌握以下關鍵點能讓文檔更實用：
- 用FastAPI構造函數參數設置全局信息（標題、描述等）；
- 通過函數註釋、Path/Query等工具類詳細描述接口和參數；
- 用tags對接口分類，便於篩選；
- 隱藏內部接口，避免文檔混亂；
- 使用Pydantic模型規範返回格式，自動生成示例。
自動生成的文檔不僅能節省手動編寫的時間，還能保證接口信息與代碼一致，讓團隊協作和用戶使用更順暢。
通過以上技巧，即使是初學者也能快速上手FastAPI的文檔生成，讓你的API變得更專業、更易用！