如何为FastAPI的APIRouter设置Swagger标签级描述？

FastAPI没有直接提供为APIRouter或include_router设置标签描述的参数，但可以通过以下两种方式实现给Swagger中标签区域添加共用描述的需求：

方法一：修改已生成的OpenAPI Schema #

在路由注册完成后，手动修改OpenAPI的schema，为对应标签添加描述：

from fastapi import APIRouter, FastAPI

router_one = APIRouter(tags=["users"])
router_two = APIRouter(tags=["products"])

app = FastAPI(description="## Description for whole application")

# 用户路由操作
@router_one.get("/users")
async def get_users():
    pass

@router_one.post("/users")
async def create_user():
    pass

# 产品路由操作
@router_two.get("/products")
async def get_products():
    pass

@router_two.post("/products")
async def create_product():
    pass

# 注册路由
app.include_router(router_one)
app.include_router(router_two)

# 为标签添加描述
def update_tag_descriptions():
    tag_info = {
        "users": "处理用户相关的所有操作，包括查询用户列表、创建新用户",
        "products": "管理产品数据，支持查询产品列表和创建新产品"
    }
    # 遍历OpenAPI标签列表，匹配并添加描述
    for tag in app.openapi()["tags"]:
        if tag["name"] in tag_info:
            tag["description"] = tag_info[tag["name"]]

update_tag_descriptions()

方法二：初始化FastAPI时预定义标签描述 #

在创建FastAPI实例时，通过openapi_tags参数提前定义所有标签的名称和描述，后续路由中使用的标签会自动关联对应的描述：

from fastapi import APIRouter, FastAPI

# 预定义所有标签的描述
predefined_tags = [
    {
        "name": "users",
        "description": "处理用户相关的所有操作，包括查询用户列表、创建新用户"
    },
    {
        "name": "products",
        "description": "管理产品数据，支持查询产品列表和创建新产品"
    }
]

# 初始化应用时传入预定义标签
app = FastAPI(
    description="## Description for whole application",
    openapi_tags=predefined_tags
)

router_one = APIRouter(tags=["users"])
router_two = APIRouter(tags=["products"])

# 用户路由操作
@router_one.get("/users")
async def get_users():
    pass

@router_one.post("/users")
async def create_user():
    pass

# 产品路由操作
@router_two.get("/products")
async def get_products():
    pass

@router_two.post("/products")
async def create_product():
    pass

# 注册路由
app.include_router(router_one)
app.include_router(router_two)

两种方法都能在Swagger UI的标签区域显示对应标签的共用描述，满足需求。

内容的提问来源于stack exchange，提问作者S.B