FastAPI接口多查询参数导致Swagger文档异常，求保留过滤与排序类分离的修复方案

嘿，我完全懂你现在的困扰——把FilterSet和Ordering两个职责分明的类作为查询参数传入接口后，Swagger文档变得乱七八糟，但你又不想把它们合并成一个类，毕竟职责分离才是合理的设计对吧？

其实问题出在你用= Query()来解析这两个BaseModel的方式上：FastAPI会把它们当成嵌套的查询参数对象，生成像filterset.first_name、ordering.ordering[0]这种怪异的参数名，不仅不符合RESTful的常用写法，还直接搞乱了Swagger的展示逻辑。

下面给你一个不用合并类的完美修复方案，分两步走：

1. 调整模型定义，给字段添加Query注解（可选但推荐） #

先给FilterSet和Ordering的字段加上Query注解，既能给Swagger补充清晰的参数描述，还能明确参数的行为逻辑：

from fastapi import FastAPI, Query, Depends
from pydantic import BaseModel
from sqlalchemy import Select, create_engine, MetaData, select
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

app = FastAPI()
url = "postgresql+psycopg2://postgres:postgres@localhost:5432/database"
engine = create_engine(url, echo=True)

class Base(DeclarativeBase):
    metadata = MetaData()

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    first_name: Mapped[str]
    last_name: Mapped[str]

class FilterSet(BaseModel):
    first_name: str | None = Query(None, description="按用户名字过滤，若要模糊匹配可自行扩展逻辑")

    def filter_queryset(self, query: Select) -> Select:
        conditions = self.model_dump(exclude_unset=True)
        if conditions:
            query = query.filter_by(**conditions)
        return query

class Ordering(BaseModel):
    ordering: list[str] | None = Query(None, description="排序字段，可重复传入；前缀-表示降序，例如：?ordering=first_name&ordering=-last_name")

    def order_queryset(self, query: Select) -> Select:
        if self.ordering:
            for field in self.ordering:
                # 处理降序标记
                if field.startswith('-'):
                    column = getattr(User, field[1:]).desc()
                else:
                    column = getattr(User, field)
                query = query.order_by(column)
        return query

2. 用Depends替代Query注入模型 #

在路径操作函数里，把原来的= Query()改成= Depends()，这样FastAPI会把模型的字段平铺成顶层查询参数，而不是嵌套对象：

@app.get("/")
async def index(filterset: FilterSet = Depends(), ordering: Ordering = Depends()):
    query = select(User)
    query = filterset.filter_queryset(query)
    query = ordering.order_queryset(query)
    # 这里可以添加数据库执行逻辑，比如：
    # with engine.connect() as conn:
    #     result = conn.execute(query)
    #     users = result.fetchall()
    # return {"users": users}
    return {"message": "接口正常，参数解析正确"}

这样修改后，Swagger文档会恢复正常：

• 过滤参数first_name单独清晰展示
• 排序参数ordering会生成一个可重复添加值的输入框，符合常见的API使用习惯
• 两个类的职责依然完全分离，不用做任何合并

如果你还想在Swagger里把过滤和排序参数分组展示，可以给每个模型添加Config配置，加上分组标记（默认Swagger UI可能需要小调整，但不影响核心功能）：

class FilterSet(BaseModel):
    first_name: str | None = Query(None, description="按用户名字过滤")

    class Config:
        openapi_extra = {"x-group": "过滤参数"}

class Ordering(BaseModel):
    ordering: list[str] | None = Query(None, description="排序字段，支持多值")

    class Config:
        openapi_extra = {"x-group": "排序参数"}

内容来源于stack exchange