FastAPI扩展APIRouter添加tags_metadata方案可行性咨询

核心逻辑说明 #

• 这种通过动态给APIRouter实例添加自定义属性的方式在Python里完全合法，因为Python是动态类型语言，允许给实例追加新属性
• FastAPI的openapi_tags属性本身就是用来接收标签元数据列表的，只要每个元数据项的格式符合OpenAPI规范（包含name、description等字段），就能正常渲染到自动生成的API文档中

代码修正与优化 #

原代码存在一处语法错误：app = FastAPI只是引用类而非创建实例，需改为app = FastAPI()。修正后的完整可运行代码如下：

from fastapi import APIRouter, FastAPI

user_router = APIRouter(
    prefix="/user", tags=["users"]
)
user_router.tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    }
]

def collect_openapi_tags(*routers):
    tags = []
    for router in routers:
        if hasattr(router, 'tags_metadata'):
            tags.extend(router.tags_metadata)
    return tags

app = FastAPI()
app.openapi_tags = collect_openapi_tags(user_router)

# 示例路由用于测试文档渲染
@user_router.get("/me")
def read_current_user():
    return {"user_id": "current_user"}

# 别忘了挂载路由
app.include_router(user_router)

更规范的实现方式 #

如果想避免手动追加属性的随意性，可以通过继承APIRouter自定义子类，内置tags_metadata参数：

from fastapi import APIRouter, FastAPI

class CustomAPIRouter(APIRouter):
    def __init__(self, *args, tags_metadata=None, **kwargs):
        super().__init__(*args, **kwargs)
        self.tags_metadata = tags_metadata or []

# 使用自定义路由类
user_router = CustomAPIRouter(
    prefix="/user", 
    tags=["users"],
    tags_metadata=[
        {
            "name": "users",
            "description": "Operations with users. The **login** logic is also here.",
        }
    ]
)

# 收集逻辑不变
def collect_openapi_tags(*routers):
    tags = []
    for router in routers:
        if hasattr(router, 'tags_metadata'):
            tags.extend(router.tags_metadata)
    return tags

app = FastAPI()
app.openapi_tags = collect_openapi_tags(user_router)

这种方式代码可读性更强，也能统一团队内的路由定义规范。

内容的提问来源于stack exchange，提问作者Артур Шаймарданов