FastAPI 教程翻译 - 用户指南 11 - 模式扩展 - 示例

FastAPI 教程翻译 - 用户指南 11 - 模式扩展 - 示例

FastAPI Tutorial - User Guide - Schema Extra - Example

You can define extra information to go in JSON Schema.

您可以定义其他信息以放入 JSON 模式。

A common use case is to add an example that will be shown in the docs.

一个常见的用例是添加一个将在文档中显示的 example。

There are several ways you can declare extra JSON Schema information.

有几种方法可以声明额外的 JSON 模式信息。

Pydantic schema_extra

You can declare an example for a Pydantic model using Config and schema_extra, as described in Pydantic’s docs: Schema customization:

您可以使用 Config 和 schema_extra 声明一个 Pydantic 模型的示例，如 Pydantic’s docs: Schema customization：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    class Config:
        schema_extra = {
            "example": {
                "name": "Foo",
                "description": "A very nice Item",
                "price": 35.4,
                "tax": 3.2,
            }
        }


@app.put("/items/{item_id}")
async def update_item(*, item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

That extra info will be added as-is to the output JSON Schema.

该额外信息将原样添加到输出 JSON 模式中。

Field additional arguments

Field 附加参数

In Field, Path, Query, Body and others you’ll see later, you can also declare extra info for the JSON Schema by passing any other arbitrary arguments to the function, for example, to add an example:

在稍后将看到的 Field、Path、Query、Body 等中，您还可以通过将其他任意参数传递给函数来声明 JSON 模式的额外信息，例如，添加一个 example：

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(..., example="Foo")
    description: str = Field(None, example="A very nice Item")
    price: float = Field(..., example=35.4)
    tax: float = Field(None, example=3.2)


@app.put("/items/{item_id}")
async def update_item(*, item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Warning

警告

Have in mind that those extra arguments passed won’t add any validation, only annotation, for documentation purposes.

请记住，出于文档目的，传递的那些额外参数不会添加任何验证，而只会添加注释。

Body additional arguments

Body 附加参数

The same way you can pass extra info to Field, you can do the same with Path, Query, Body, etc.

您可以将额外的信息传递给 Field 的方式相同，也可以对 Path、Query、Body 等进行相同的操作。

For example, you can pass an example for a body request to Body:

例如，您可以将主体请求的 example传递给 Body：

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Item = Body(
        ...,
        example={
            "name": "Foo",
            "description": "A very nice Item",
            "price": 35.4,
            "tax": 3.2,
        },
    )
):
    results = {"item_id": item_id, "item": item}
    return results

Example in the docs UI

docs UI 中的示例

With any of the methods above it would look like this in the /docs:

使用以上任何一种方法，它在 /docs 中都是这样的：

Technical Details

技术细节

About example vs examples…

关于 example 与 examples……

JSON Schema defines a field examples in the most recent versions, but OpenAPI is based on an older version of JSON Schema that didn’t have examples.

JSON 模式在最新版本中定义了一个字段 examples，但 OpenAPI 是基于没有 examples 的 JSON 模式的旧版本。

So, OpenAPI defined its own example for the same purpose (as example, not examples), and that’s what is used by the docs UI (using Swagger UI).

因此，OpenAPI 出于相同的目的定义了自己的 example（就像 example 而不是 examples），这就是 docs UI（使用 Swagger UI ）所使用的。

So, although example is not part of JSON Schema, it is part of OpenAPI, and that’s what will be used by the docs UI.

因此，尽管 example 不是 JSON 模式的一部分，但它是 OpenAPI 的一部分，而这正是 docs UI 所使用的。

Other info

其它信息

The same way, you could add your own custom extra info that would be added to the JSON Schema for each model, for example to customize a frontend user interface, etc.

同样，您可以添加自己的自定义额外信息，这些信息将添加到每个模型的 JSON 模式中，例如，以自定义前端用户界面等。