什麼是Swagger UI？¶
FastAPI默認使用Swagger UI作爲API文檔工具，它能可視化展示你的API接口，讓開發者輕鬆測試和理解接口參數與返回結果。但默認界面可能比較單調，不夠貼合項目風格。自定義Swagger UI可以讓文檔更專業、美觀，甚至添加品牌元素，提升用戶體驗。
一、修改基本信息：讓文檔更“個性化”¶
最基礎的美化是修改Swagger UI的標題、描述、版本等信息，這些參數直接在創建FastAPI應用時設置即可。
示例代碼：
from fastapi import FastAPI
app = FastAPI(
title="我的在線圖書API", # Swagger UI頂部標題
description="這是一個管理圖書信息的API，支持增刪改查。\n**文檔更新日期**：2023-10-01", # 描述文本（支持換行）
version="1.0.0", # API版本
terms_of_service="https://example.com/terms", # 服務條款鏈接
contact={ # 聯繫方式
"name": "開發團隊",
"email": "dev@example.com"
}
)
@app.get("/books")
def get_books():
return [{"id": 1, "title": "Python入門", "author": "張三"}]
效果：訪問/docs後，Swagger UI頂部會顯示你設置的標題、描述和版本，右側還會出現聯繫方式和服務條款鏈接。
二、自定義主題樣式：讓界面更“好看”¶
默認Swagger UI是藍白配色，你可以通過CSS修改背景、按鈕顏色、字體等，打造獨特風格。以下是兩種簡單方法：
方法1：直接注入CSS（適合快速修改）¶
通過中間件在Swagger UI頁面加載時注入自定義CSS，無需額外創建文件。
示例代碼：
from fastapi import Request, FastAPI
from fastapi.responses import HTMLResponse
app = FastAPI()
@app.middleware("http")
async def custom_swagger_css(request: Request, call_next):
response = await call_next(request)
# 僅對Swagger UI頁面生效
if request.url.path == "/docs" and response.status_code == 200:
# 注入自定義CSS
custom_css = """
<style>
/* 背景顏色 */
body {
background-color: #f8f9fa;
font-family: "Microsoft YaHei", sans-serif; /* 換字體 */
}
/* 頂部導航欄顏色 */
.swagger-ui .topbar {
background-color: #2c3e50;
}
/* 按鈕顏色 */
.btnTry {
background-color: #3498db;
color: white;
border-color: #2980b9;
}
/* 按鈕 hover 效果 */
.btnTry:hover {
background-color: #2980b9;
}
/* 標題顏色 */
h2 {
color: #2c3e50;
}
</style>
"""
# 將CSS插入到HTML的<head>標籤後
body = response.body.decode()
head_start = body.find("<head>")
if head_start != -1:
new_body = body[:head_start+5] + custom_css + body[head_start+5:]
response.body = new_body.encode()
return response
效果：背景變爲淺灰色，頂部導航欄變黑，按鈕和標題顏色也會變化。
方法2：使用靜態文件注入CSS（適合複雜樣式）¶
如果需要更復雜的樣式（如自定義Logo、背景圖），可以將CSS放在靜態文件中。
- 創建靜態文件目錄：在項目根目錄下新建
static文件夾，並放入custom.css：
/* static/custom.css */
/* 替換Swagger默認Logo */
.swagger-ui .topbar .link img {
content: url('/static/logo.png'); /* 替換爲你的Logo路徑 */
height: 30px;
width: auto;
}
/* 修改按鈕顏色 */
.btnExecute {
background-color: #4CAF50 !important;
border-color: #45a049 !important;
}
/* 調整字體大小 */
.swagger-ui .opblock .section {
font-size: 14px;
}
- 在FastAPI中關聯靜態文件：
from fastapi.staticfiles import StaticFiles
app.mount("/static", StaticFiles(directory="static"), name="static")
- 注入CSS到Swagger UI：通過在HTML中添加
<link>標籤引入自定義CSS（需在中間件或模板中處理，也可直接在Swagger UI的HTML模板中硬編碼）。
三、隱藏敏感信息：讓文檔更“專業”¶
默認Swagger UI會展示所有字段，若需隱藏敏感信息（如密碼、token），可通過以下方式：
1. 隱藏Pydantic模型字段¶
在Pydantic模型中用Field(exclude=True)隱藏字段：
from pydantic import BaseModel, Field
class User(BaseModel):
id: int
name: str
password: str = Field(..., exclude=True) # 隱藏password字段
2. 隱藏路徑操作返回字段¶
在接口中用response_model_exclude指定排除的字段：
@app.get("/user", response_model_exclude=["password"])
def get_user():
return {"id": 1, "name": "Alice", "password": "secret"}
四、進階技巧：更深度的定製¶
- 修改頁面佈局：通過CSS調整最大寬度（如
max-width: 1200px）或隱藏側邊欄。 - 添加自定義操作說明：在Swagger UI中添加“使用提示”，可在描述文本中用Markdown格式寫註釋（FastAPI支持Markdown渲染）。
- 替換“Try it out”按鈕：通過CSS修改按鈕圖標或文字，需結合圖標字體（如Font Awesome）。
總結¶
自定義Swagger UI的核心是通過基本信息配置、CSS樣式注入和模型/接口參數控制實現。初學者可從修改標題、按鈕顏色等簡單操作開始，逐步嘗試更復雜的樣式調整。記住：CSS選擇器可能隨Swagger UI版本變化，建議結合版本兼容性測試使用。
通過這些技巧，你的API文檔不僅能清晰展示接口，還能成爲項目品牌的一部分，讓開發者體驗更流暢！