如何在FastAPI中让Swagger UI识别依赖注入的列表查询参数

在开发使用依赖注入且包含列表字段的FastAPI应用时，Swagger UI会自动将该参数归入请求体：

from fastapi import FastAPI, Query, Depends
import uvicorn
from pydantic import BaseModel, Field
from typing import List


class QueryParams(BaseModel):
    name: str = Field(...)
    ages: List[int] = Field([])


app = FastAPI()


@app.get("/test")
def test(query: QueryParams = Depends()):
    return "hi"

uvicorn.run(app)

这意味着无法在Swagger UI中测试该接口。即使将字段改为Query，问题仍未解决：

from fastapi import FastAPI, Query, Depends
import uvicorn
from pydantic import BaseModel, Field
from typing import List


class QueryParams(BaseModel):
    name: str = Field(...)
    ages: List[int] = Query([])  # <-- 使用Query


app = FastAPI()


@app.get("/test")
def test(query: QueryParams = Depends()):
    return "hi"

uvicorn.run(app)

但如果将列表参数直接放在路由函数中，就能正常显示在Swagger UI的查询参数区域：

from fastapi import FastAPI, Query, Depends
import uvicorn
from pydantic import BaseModel, Field
from typing import List


class QueryParams(BaseModel):
    name: str = Field(...)


app = FastAPI()


@app.get("/test")
def test(query: QueryParams = Depends(), ages: List[int] = Query([])):
    return "hi"

uvicorn.run(app)

如何让Swagger UI识别BaseModel中通过依赖注入传递的列表查询参数？

要让BaseModel中的列表字段被Swagger UI识别为查询参数，有三种可靠方式：

1. 给模型依赖标记Query并配置字段元数据 #

在BaseModel的列表字段中，通过Field的metadata参数传入Query配置，同时在依赖注入时指定Query作为解析器：

from fastapi import FastAPI, Query, Depends
import uvicorn
from pydantic import BaseModel, Field
from typing import List


class QueryParams(BaseModel):
    name: str = Field(...)
    ages: List[int] = Field(default=[], metadata={"query": Query([])})


app = FastAPI()


@app.get("/test")
def test(query: QueryParams = Depends(Query)):
    return "hi"

uvicorn.run(app)

这种方式会明确告诉FastAPI将模型所有字段解析为查询参数，Swagger UI会同步显示对应的输入区域。

2. 使用fastapi-utils的QueryModel基类 #

借助第三方库fastapi-utils提供的QueryModel，它会自动将模型字段映射为查询参数，无需额外配置：

先安装依赖：

pip install fastapi-utils

修改代码：

from fastapi import FastAPI, Depends
import uvicorn
from fastapi_utils.cbv import QueryModel
from typing import List


class QueryParams(QueryModel):
    name: str
    ages: List[int] = []


app = FastAPI()


@app.get("/test")
def test(query: QueryParams = Depends()):
    return "hi"

uvicorn.run(app)

3. 手动修改OpenAPI规范（特殊场景用） #

如果以上方法不适用，可以直接修改接口的OpenAPI扩展字段，强制指定参数位置：

from fastapi import FastAPI, Query, Depends
import uvicorn
from pydantic import BaseModel, Field
from typing import List


class QueryParams(BaseModel):
    name: str = Field(...)
    ages: List[int] = Field([])


app = FastAPI()


@app.get("/test", openapi_extra={
    "parameters": [
        {
            "name": "ages",
            "in": "query",
            "required": False,
            "schema": {"type": "array", "items": {"type": "integer"}},
            "style": "form"
        }
    ]
})
def test(query: QueryParams = Depends()):
    return "hi"

uvicorn.run(app)

这种方式较为繁琐，仅适合个别特殊场景。

内容的提问来源于stack exchange，提问作者Tom McLean