当response_model是模型列表时，如何为FastAPI文档指定多个示例？

Question

我正在用 python 编写一个 FastAPI 应用程序，我想使用自动生成的 openapi 文档。我特别想指定响应值的示例。response_model当是继承自 pydantic's 的类时，我知道该怎么做BaseModel，但是当它是此类类的列表时，我遇到了麻烦。这是一个最小的例子：

from fastapi import FastAPI

from typing import List
from pydantic import BaseModel, Field


class Person(BaseModel):
    name: str = Field(
        ...,
        title="Name",
        description="The name of the person",
        example="Alice"
    )

    age: int = Field(
        ...,
        title="Age",
        description="The age of the person",
        example=83
    )

    class Config:
        schema_extra = {
            'examples': [
                {
                    "name": "Alice",
                    "age": 83
                },
                {
                    "name": "Bob",
                    "age": 77
                }
            ]
        }


app = FastAPI()


@app.get('/person', response_model=Person)
def person():
    return {
        "name": "Alice",
        "age": 83
    }


@app.get('/people', response_model=List[Person])
def people():
    return [
        {
            "name": "Alice",
            "age": 83
        },
        {
            "name": "Bob",
            "age": 77
        }
    ]

在自动生成的 openapi 文档中，成功响应的示例/person值为

{
  "name": "Alice",
  "age": 83
}

这就是我想要的。然而，因为/people它是

[
  {
    "name": "Alice",
    "age": 83
  }
]

但我更希望它是

[
  {
    "name": "Alice",
    "age": 83
  },
  {
    "name": "Bob",
    "age": 77
  }
]

有什么办法可以实现这一点吗？先感谢您！

Answer 1

您可以在响应参数中指定您的示例：

@app.get('/people', response_model=List[Person], responses={
    200: {
        "description": "People successfully found",
        "content": {
            "application/json": {
                "example": [
                    {
                        "name": "Alice",
                        "age": 83
                    },
                    {
                        "name": "Bob",
                        "age": 77
                    }
                ]
            }
        }
    },
    404: {"description": "People not found"}
})
def people():
    return [
        {
            "name": "Alice",
            "age": 83
        },
        {
            "name": "Bob",
            "age": 77
        }
    ]

使用此代码，为状态代码 200 指定示例，但您也可以配置错误示例（或者，如果您不希望它出现在 openapi 中，则可以删除 404 条目）。

有关更多信息，您可以查看 FastAPI 文档：https://fastapi.tiangolo.com/advanced/additional-responses/