如何在FastAPI的Swagger UI文档中标记响应体为列表类型？

你当前的问题核心是：versions_info定义的是单个对象模型，直接用它作为响应类型时，Swagger只会展示单个对象结构，但你需要返回的是该模型的列表。

下面是两种针对性的解决方法：

场景1：直接返回纯列表响应 #

只需要在路由的response_model参数里指定List[versions_info]（Python 3.9+也可以直接用list[versions_info]），代码示例：

from fastapi import FastAPI
from pydantic import BaseModel, Field
from typing import List  # Python 3.9+可省略，直接用list

app = FastAPI()

class versions_info(BaseModel):
    """ List of versions """
    version : str = Field(..., title="Version",example="2.1.1")
    url :   str = Field(..., title="Url",example="https://ocpi.wedwe.ww/ocpi/2.1.1/")

@app.get("/versions", response_model=List[versions_info])
def get_versions():
    return [
        {"version": "2.1.1", "url": "https://www.server.com/ocpi/2.1.1/"},
        {"version": "2.2", "url": "https://www.server.com/ocpi/2.2/"}
    ]

场景2：需要额外字段的列表响应 #

如果后续要给响应添加其他字段（比如总条数），可以定义一个包含列表字段的父模型：

from fastapi import FastAPI
from pydantic import BaseModel, Field
from typing import List

app = FastAPI()

class versions_info(BaseModel):
    """ List of versions """
    version : str = Field(..., title="Version",example="2.1.1")
    url :   str = Field(..., title="Url",example="https://ocpi.wedwe.ww/ocpi/2.1.1/")

class VersionListResponse(BaseModel):
    versions: List[versions_info] = Field(..., title="版本列表")
    total: int = Field(..., title="总版本数", example=2)

@app.get("/versions", response_model=VersionListResponse)
def get_versions():
    return {
        "versions": [
            {"version": "2.1.1", "url": "https://www.server.com/ocpi/2.1.1/"},
            {"version": "2.2", "url": "https://www.server.com/ocpi/2.2/"}
        ],
        "total": 2
    }

修改完成后，Swagger UI里的响应体就会显示为你需要的数组格式，同时自动匹配示例结构。

内容的提问来源于stack exchange，提问作者Pavel Gribov