FastAPI 生成的 API 文档下拉列表用于显示请求正文的多个示例，但仅显示 1 个示例

Question

我正在关注FastAPI教程，特别是有关显示多个示例的部分：https://fastapi.tiangolo.com/tutorial/schema-extra-example/.

我复制了代码：

from typing import Optional

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None


@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Item = Body(
        ...,
        examples={
            "normal": {
                "summary": "A normal example",
                "description": "A **normal** item works correctly.",
                "value": {
                    "name": "Foo",
                    "description": "A very nice Item",
                    "price": 35.4,
                    "tax": 3.2,
                },
            },
            "converted": {
                "summary": "An example with converted data",
                "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                "value": {
                    "name": "Bar",
                    "price": "35.4",
                },
            },
            "invalid": {
                "summary": "Invalid data is rejected with an error",
                "value": {
                    "name": "Baz",
                    "price": "thirty five point four",
                },
            },
        },
    ),
):
    results = {"item_id": item_id, "item": item}
    return results

...与页面上显示的完全一样，我使用 Uvicorn 运行它。在我的屏幕上，我没有看到请求正文示例字典中包含 3 个示例的任何下拉菜单。我所看到的只是一个示例值，其中包含字段所需的类型。

为什么会这样？为什么这对我不起作用？

这就是我应该得到的：

但这就是我得到的：

Answer 1

我不确定这是否有帮助： https://github.com/tiangolo/fastapi/pull/1267#issuecomment-762557261 这意味着两件事：

1. 例子需要进去

   Item.Config.schema_extra

2. examples 参数必须引用类中的数据

类似这样的：

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

    class Config:
        schema_extra = {
            "examples": {
                "normal": {
                    "summary": "A normal example",
                    "description": "A **normal** item works correctly.",
                    "value": {
                        "name": "Foo",
                        "description": "A very nice Item",
                        "price": 35.4,
                        "tax": 3.2,
                    },
                },
                "converted": {
                    "summary": "An example with converted data",
                    "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                    "value": {
                        "name": "Bar",
                        "price": "35.4",
                    },
                },
                "invalid": {
                    "summary": "Invalid data is rejected with an error",
                    "value": {
                        "name": "Baz",
                        "price": "thirty five point four",
                    },
                },
            }
        }


@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Item = Body(
        None,
        examples=Item.Config.schema_extra["examples"],
    ),
):
    results = {"item_id": item_id, "item": item}
    return results

它帮助了我！

Answer 2

这是

>0.99.0

和

<0.103.0

上的 FastAPI 的问题，特别是 FastAPI 的内部更新以支持基于新 JSON 架构的 OpenAPI 3.1 ，其中包括在生成的 openapi.json

 中定义多个示例

的规范。

不幸的是，（目前）Swagger 尚未完全支持这个用于定义多个示例的新规范，如 Github 上的相关讨论中所述：

...问题在于 Swagger UI 需要修复 - FastAPI 正在向其传递有效的架构以及所有示例，但只是当这些示例位于 JSON 架构中时，它们不会将这些示例呈现为下拉列表.

因此，FastAPI 目前已将其修复，如 https://fastapi.tiangolo.com/tutorial/schema-extra-example/#swagger-ui-and-openapi-specific-examples:

中所述

现在，由于 Swagger UI 不支持多个 JSON Schema 示例（截至 2023 年 8 月 26 日），用户无法在文档中显示多个示例。

为了解决这个问题，FastAPI

0.103.0

添加了对使用新参数

examples

声明相同的旧 OpenAPI 特定

openapi_examples

字段的支持。 🤓

您需要做的唯一更改是将 FastAPI 版本至少提升到

0.103.0

并更新代码以使用

openapi_examples

而不是

examples

：

旧文档（与问题中的文档相同）：

@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Item = Body(
        ...,
        examples={               # <-- THIS.

从

0.103.0

开始的新方式：

@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Annotated[
        Item,
        Body(
            openapi_examples={   # <-- THIS.

...Swagger UI 文档应显示用于选择示例的下拉列表，如文档所示。

注意，将 FastAPI 提升到

>0.100.0

可能 也会将 Pydantic 依赖关系提升到 v2，具体取决于您在项目中管理依赖关系的方式。请参阅 FastAPI 的

0.100.0

发行说明。

---

更多技术细节请参见：

• Github 上的讨论：
  • “具有多个示例的正文”仅显示单个示例 v0.100.1 #9958
  • 多个请求示例无法使用 pydantic
• FastAPI 相关 PR：
  • v0.100 中的多体示例回归