当response_mode是一个模型列表时，我如何为FastAPI文档指定几个示例

Question

我正在用python编写一个FastAPI应用程序，我想使用自动生成的openapi文档。特别是，我想指定响应值的示例。当response_model是从pydantic的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指定的，但您也可以为错误配置示例(或者，如果您不希望404条目出现在openapi中，则可以删除它(。

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