FastAPI 中 tags 参数用于驱动 Swagger UI 和 ReDoc 文档的标签分组，必须为 list[str] 类型，如 tags=["users"]；未设置则归入"default"分组，配合 openapi_tags 可添加描述与排序。
FastAPI 中 tags 参数的作用和基本写法
FastAPI 的 tags 不是用来“分组文档”的装饰性字段，而是直接驱动 Swagger UI 和 ReDoc 文档结构的核心配置项。只要给 app.get()、app.post() 等路由函数传入 tags 列表，对应接口就会归入指定标签页。
常见错误是把 tags 当成字符串或忽略类型——它必须是 list[str]，哪怕只有一个分组也要写成 tags=["users"]，而不是 tags="users"。
-
tags值区分大小写，["Users"]和["users"]会被视为两个不同分组 - 同一
tags值下多个接口会自动聚合，无需额外配置 - 未设
tags的接口默认归入 “default” 分组（文字显示为 “default”）
用 tags 实现多层级语义分组的实操要点
FastAPI 本身不支持嵌套标签（如 “users > profile”），但可以通过命名约定模拟层级感，比如用冒号或点号分隔：tags=["users:profile"]、tags=["admin.users"]。Swagger UI 会原样显示，靠命名统一就能达成视觉分组效果。
更实用的做法是结合 prefix 和 tags：在 APIRouter 初始化时设 prefix="/v1/users"，再统一给该 router 下所有路由加 tags=["Users"]。这样逻辑清晰，也避免单个路由重复写 prefix。
立即学习“Python免费学习笔记（深入）”；
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 同一个
tags名称在多个 router 中复用，文档会自动合并显示，不是各自独立页签 - 若想强制拆成多个同名页签（不推荐），只能改名，例如
["Users (Admin)"]和["Users (Public)"] - 使用
include_router()时，router 自身的tags参数会作为默认值，被子路由的tags覆盖
配合 OpenAPI 配置增强分组可读性
仅靠 tags 字符串不够直观，建议同步配置 openapi_tags 参数传给 FastAPI() 实例，为每个 tag 补充描述和排序顺序：
app = FastAPI(
openapi_tags=[
{"name": "Users", "description": "用户注册、登录与资料管理"},
{"name": "Orders", "description": "订单创建、查询与状态变更"},
{"name": "Admin", "description": "后台管理专用接口", "x-display": "hidden"}, # 非标准字段，部分 UI 可识别
]
)注意：openapi_tags 中的 name 必须与路由中 tags 的字符串完全一致，否则不会关联上。
- 缺失
openapi_tags条目不会报错，只是对应分组没描述、无排序保障 - OpenAPI spec 本身不定义排序，但 Swagger UI 按
openapi_tags列表顺序渲染 tab - 不要依赖
x-开头的扩展字段做关键逻辑，兼容性差
容易被忽略的 tags 作用域陷阱
tags 是路由级配置，不是模块级或函数级元数据。它只影响 OpenAPI 文档生成，对运行时行为（如中间件、依赖注入、权限校验）零影响。
最常踩的坑是误以为给某个 Depends() 或 BaseModel 加注释就能联动分组——不行。所有分组逻辑必须显式落在 @app.get(..., tags=[...]) 或 router.add_api_route(..., tags=[...]) 这类调用上。
- 使用
APIRouter时，router.get(..., tags=[...])的tags优先级高于router初始化时的tags参数 - 动态生成路由（如循环注册）时，确保每次调用都传入明确的
tags，别因变量复用导致所有接口挤进同一个 tag - 测试环境启用了
docs_url=None？那再怎么配tags也看不到分组效果
实际项目里，tag 名称一致性比技巧更重要。一个拼写错误、一处大小写不一致，就可能导致本该合并的接口散落在不同 tab 里，排查起来反而更花时间。
