fastapi/docs/zh/docs/tutorial/schema-extra-example.md

声明请求示例数据

你可以为你的应用将接收的数据声明示例。

这里有几种实现方式。

Pydantic 模型中的额外 JSON Schema 数据

你可以为一个 Pydantic 模型声明 examples，它们会被添加到生成的 JSON Schema 中。

{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}

这些额外信息会原样添加到该模型输出的 JSON Schema 中，并会在 API 文档中使用。

你可以使用属性 model_config，它接收一个 dict，详见 Pydantic 文档：配置。

你可以设置 "json_schema_extra"，其值为一个 dict，包含你希望出现在生成 JSON Schema 中的任意附加数据，包括 examples。

/// tip | 提示

你也可以用同样的技巧扩展 JSON Schema，添加你自己的自定义额外信息。

例如，你可以用它为前端用户界面添加元数据等。

///

/// info | 信息

OpenAPI 3.1.0（自 FastAPI 0.99.0 起使用）增加了对 examples 的支持，它是 JSON Schema 标准的一部分。

在此之前，只支持使用单个示例的关键字 example。OpenAPI 3.1.0 仍然支持它，但它已被弃用，并不属于 JSON Schema 标准。因此，建议你把 example 迁移到 examples。🤓

你可以在本页末尾阅读更多内容。

///

Field 的附加参数

在 Pydantic 模型中使用 Field() 时，你也可以声明额外的 examples：

{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}

JSON Schema 中的 examples - OpenAPI

在以下任意场景中使用：

• Path()
• Query()
• Header()
• Cookie()
• Body()
• Form()
• File()

你也可以声明一组 examples，这些带有附加信息的示例将被添加到它们在 OpenAPI 中的 JSON Schema 里。

带有 examples 的 Body

这里我们向 Body() 传入 examples，其中包含一个期望的数据示例：

{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}

文档 UI 中的示例

使用上述任一方法，在 /docs 中看起来会是这样：

带有多个 examples 的 Body

当然，你也可以传入多个 examples：

{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}

这样做时，这些示例会成为该请求体数据内部 JSON Schema 的一部分。

不过，在撰写本文时，用于展示文档 UI 的 Swagger UI 并不支持显示 JSON Schema 中数据的多个示例。但请继续阅读，下面有一种变通方法。

OpenAPI 特定的 examples

在 JSON Schema 支持 examples 之前，OpenAPI 就已支持一个同名但不同的字段 examples。

这个面向 OpenAPI 的 examples 位于 OpenAPI 规范的另一处。它放在每个路径操作的详细信息中，而不是每个 JSON Schema 里。

而 Swagger UI 早就支持这个特定的 examples 字段。因此，你可以用它在文档 UI 中展示不同的示例。

这个 OpenAPI 特定字段 examples 的结构是一个包含多个示例的 dict（而不是一个 list），每个示例都包含会被添加到 OpenAPI 的额外信息。

这不放在 OpenAPI 内部包含的各个 JSON Schema 里，而是直接放在路径操作上。

使用 openapi_examples 参数

你可以在 FastAPI 中通过参数 openapi_examples 来声明这个 OpenAPI 特定的 examples，适用于：

• Path()
• Query()
• Header()
• Cookie()
• Body()
• Form()
• File()

这个 dict 的键用于标识每个示例，每个值是另一个 dict。

examples 中每个具体示例的 dict 可以包含：

• summary：该示例的简短描述。
• description：较长描述，可以包含 Markdown 文本。
• value：实际展示的示例，例如一个 dict。
• externalValue：value 的替代项，指向该示例的 URL。不过它的工具支持度可能不如 value。

你可以这样使用：

{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}

文档 UI 中的 OpenAPI 示例

当把 openapi_examples 添加到 Body() 后，/docs 会如下所示：

技术细节

/// tip | 提示

如果你已经在使用 FastAPI 版本 0.99.0 或更高版本，你大概率可以跳过这些细节。

它们对更早版本（OpenAPI 3.1.0 尚不可用之前）更相关。

你可以把这当作一堂简短的 OpenAPI 和 JSON Schema 历史课。🤓

///

/// warning | 警告

以下是关于 JSON Schema 和 OpenAPI 标准的非常技术性的细节。

如果上面的思路对你已经足够可用，你可能不需要这些细节，可以直接跳过。

///

在 OpenAPI 3.1.0 之前，OpenAPI 使用的是一个更旧且经过修改的 JSON Schema 版本。

当时 JSON Schema 没有 examples，所以 OpenAPI 在它修改过的版本中添加了自己的 example 字段。

OpenAPI 还在规范的其他部分添加了 example 和 examples 字段：

• Parameter Object（规范中），被 FastAPI 的以下内容使用：
  • Path()
  • Query()
  • Header()
  • Cookie()
• Request Body Object 中的 content 字段里的 Media Type Object（规范中），被 FastAPI 的以下内容使用：
  • Body()
  • File()
  • Form()

/// info | 信息

这个旧的、OpenAPI 特定的 examples 参数，自 FastAPI 0.103.0 起改名为 openapi_examples。

///

JSON Schema 的 examples 字段

后来，JSON Schema 在新版本的规范中添加了 examples 字段。

随后新的 OpenAPI 3.1.0 基于最新版本（JSON Schema 2020-12），其中包含了这个新的 examples 字段。

现在，这个新的 examples 字段优先于旧的单个（且自定义的）example 字段，后者已被弃用。

JSON Schema 中这个新的 examples 字段只是一个由示例组成的 list，而不是像上面提到的 OpenAPI 其他位置那样带有额外元数据的 dict。

/// info | 信息

即使在 OpenAPI 3.1.0 发布、并与 JSON Schema 有了这种更简单的集成之后，有一段时间里，提供自动文档的 Swagger UI 并不支持 OpenAPI 3.1.0（它自 5.0.0 版本起已支持 🎉）。

因此，FastAPI 0.99.0 之前的版本仍然使用低于 3.1.0 的 OpenAPI 版本。

///

Pydantic 与 FastAPI 的 examples

当你在 Pydantic 模型中添加 examples，通过 schema_extra 或 Field(examples=["something"])，这些示例会被添加到该 Pydantic 模型的 JSON Schema 中。

这个 Pydantic 模型的 JSON Schema 会被包含到你的 API 的 OpenAPI 中，然后在文档 UI 中使用。

在 FastAPI 0.99.0 之前的版本（0.99.0 及以上使用更新的 OpenAPI 3.1.0），当你在其他工具（Query()、Body() 等）中使用 example 或 examples 时，这些示例不会被添加到描述该数据的 JSON Schema 中（甚至不会添加到 OpenAPI 自己的 JSON Schema 版本中），而是会直接添加到 OpenAPI 的路径操作声明中（在 OpenAPI 使用 JSON Schema 的部分之外）。

但现在 FastAPI 0.99.0 及以上使用 OpenAPI 3.1.0（其使用 JSON Schema 2020-12）以及 Swagger UI 5.0.0 及以上后，一切更加一致，示例会包含在 JSON Schema 中。

Swagger UI 与 OpenAPI 特定的 examples

此前，由于 Swagger UI 不支持多个 JSON Schema 示例（截至 2023-08-26），用户无法在文档中展示多个示例。

为了解决这个问题，FastAPI 0.103.0 通过新增参数 openapi_examples，为声明同样的旧式 OpenAPI 特定 examples 字段提供了支持。🤓

总结

我曾经说我不太喜欢历史……结果现在在这儿上“技术史”课。😅

简而言之，升级到 FastAPI 0.99.0 或更高版本，一切会更简单、一致、直观，你也不必了解这些历史细节。😎