什么是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文档不仅能清晰展示接口，还能成为项目品牌的一部分，让开发者体验更流畅！