如何在 API 文档中查看列表中返回的架构是什么？

Question

如何在 API 文档中查看列表中返回的架构是什么？

response={
    200: list[PersonSchema]
}

令我困扰的是，通过查看文档，此响应的内容是 PersonSchema 类型列表的信息丢失了。

---

代码示例：

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

在返回上述架构的单个对象的端点上：

@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)

API 明确显示 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)]

这次 API 根本没有显示有关 Schema 的信息。其中有一个通用的“响应”和一个“项目”属性。仅通过查看此端点，不可能知道返回的架构是什么。

Answer 1

首先检查

list[PersonSchema]

是否在您的 OpenAPI 架构 中正确定义。这应该涉及将

PersonSchema

定义为组件，然后在返回这些对象列表的端点中引用它。

将

PersonSchema

定义为 Component:

components:
  schemas:
    PersonSchema:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        age:
          type: integer

端点定义中参考

PersonSchema

：

paths:
  /person/:
    get:
      responses:
        200:
          description: A list of persons
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PersonSchema'

对于返回

PersonSchema

对象列表的端点，请确保框架的语法正确地将返回类型指定为架构对象列表。
例如，这假设一个基于 Python 的框架，如 FastAPI，但该概念适用于不同的语言和框架：

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

app = FastAPI()
playbook_routes_api = APIRouter()

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

@playbook_routes_api.get("/person/", response_model=List[PersonSchema])
def get_persons():
    return [PersonSchema(id=1, name='Brian', age=12), PersonSchema(id=2, name='John', age=31)]

app.include_router(playbook_routes_api)