如何在API文档中查看列表形式返回结果对应的Schema详情？

问题说明 #

当API接口返回list[PersonSchema]这类列表形式的Schema时，API文档仅展示通用的「Response」及「items」属性，无法呈现列表内PersonSchema的具体字段结构，导致无法直接知晓返回内容的Schema类型。

代码示例 #

定义PersonSchema #

class PersonSchema(Schema):
  id: int
  name: str
  age: int

可正常显示Schema的单对象接口 #

@playbook_routes_api.get(
    "/person/{person_id}",
    response={
        200: PersonSchema
    }
)
def get_person_by_id(request, person_id: int):
    return 200, PersonSchema(id=1, name='Brian', age=12)

无法显示内部Schema的列表接口 #

@playbook_routes_api.get(
    "/person/",
    response={
        200: list[PersonSchema]
    }
)
def get_persons(request):
    return 200, [PersonSchema(id=1, name='Brian', age=12), PersonSchema(id=2, name='John', age=31)]

解决方案 #

直接使用list[PersonSchema]无法让API文档解析内部Schema结构，需通过以下方式调整：

方法1：定义专门的列表Schema类 #

先创建一个包裹列表的Schema类，明确声明内部元素类型：

from typing import List

class PersonListSchema(Schema):
    items: List[PersonSchema]

再在接口中使用该列表Schema：

@playbook_routes_api.get(
    "/person/",
    response={
        200: PersonListSchema
    }
)
def get_persons(request):
    return 200, PersonListSchema(items=[
        PersonSchema(id=1, name='Brian', age=12),
        PersonSchema(id=2, name='John', age=31)
    ])

方法2：使用框架专属的列表包装类型（若支持） #

部分API文档生成框架支持直接识别List[Schema]类型（如FastAPI），如果你的框架兼容这种写法，也可以直接使用List[PersonSchema]替代原生list类型，确保文档工具能解析内部结构。

调整后，API文档将正确展示PersonSchema的具体字段信息，而非仅显示通用的列表框架。

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