Skip to content

От переводчика

Это машинный перевод (DeepSeek) статьи https://fastapi.tiangolo.com/tutorial/schema-extra-example/

Версия от 03.09.2026

Неочевидных моментов в уроке не обнаружено, но я рад сообщить, что дополнил базу инструмента для импорта модулей и классов в python классами, использующимися в уроке.

Подпишитесь на канал "Изучаем FastAPI", чтобы ссылки на инструмент работала.

 

Перевод прочих разделов документации буду по мере сил делать.

Обо мне

Объявление примеров данных запроса

Вы можете объявлять примеры данных, которые ваше приложение может получать.

Вот несколько способов сделать это.

Дополнительные данные JSON Schema в моделях Pydantic

Вы можете объявить examples для модели Pydantic, которые будут добавлены в сгенерированную JSON Schema.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "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

Эта дополнительная информация будет добавлена как есть в выходную JSON Schema для этой модели, и она будет использоваться в документации API.

Вы можете использовать атрибут model_config, который принимает dict, как описано в документации Pydantic: Конфигурация.

Вы можете установить "json_schema_extra" с dict, содержащим любые дополнительные данные, которые вы хотели бы показать в сгенерированной JSON Schema, включая examples.

Совет

Вы можете использовать ту же технику для расширения JSON Schema и добавления своей собственной дополнительной информации.

Например, вы можете использовать её для добавления метаданных для пользовательского интерфейса фронтенда и т.д.

Примечание

OpenAPI 3.1.0 (используется начиная с FastAPI 0.99.0) добавил поддержку examples, которые являются частью стандарта JSON Schema.

До этого он поддерживал только ключевое слово example с одним примером. Это всё ещё поддерживается OpenAPI 3.1.0, но является устаревшим и не является частью стандарта JSON Schema. Поэтому вам рекомендуется мигрировать example на examples. 🤓

Вы можете прочитать больше в конце этой страницы.

Дополнительные аргументы Field

При использовании Field() с моделями Pydantic вы также можете объявить дополнительные examples:

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(examples=["Foo"])
    description: str | None = Field(default=None, examples=["A very nice Item"])
    price: float = Field(examples=[35.4])
    tax: float | None = Field(default=None, examples=[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

examples в JSON Schema — OpenAPI

При использовании любого из:

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

вы также можете объявить группу examples с дополнительной информацией, которая будет добавлена в их JSON Schemas внутри OpenAPI.

Body с examples

Здесь мы передаём examples, содержащие один пример данных, ожидаемых в Body():

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@app.put("/items/{item_id}")
async def update_item(
    item_id: int,
    item: Annotated[
        Item,
        Body(
            examples=[
                {
                    "name": "Foo",
                    "description": "A very nice Item",
                    "price": 35.4,
                    "tax": 3.2,
                }
            ],
        ),
    ],
):
    results = {"item_id": item_id, "item": item}
    return results
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


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

Пример в интерфейсе документации

С любым из описанных выше методов это будет выглядеть так в /docs:

Body с несколькими examples

Вы, конечно, также можете передать несколько examples:

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Annotated[
        Item,
        Body(
            examples=[
                {
                    "name": "Foo",
                    "description": "A very nice Item",
                    "price": 35.4,
                    "tax": 3.2,
                },
                {
                    "name": "Bar",
                    "price": "35.4",
                },
                {
                    "name": "Baz",
                    "price": "thirty five point four",
                },
            ],
        ),
    ],
):
    results = {"item_id": item_id, "item": item}
    return results
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Item = Body(
        examples=[
            {
                "name": "Foo",
                "description": "A very nice Item",
                "price": 35.4,
                "tax": 3.2,
            },
            {
                "name": "Bar",
                "price": "35.4",
            },
            {
                "name": "Baz",
                "price": "thirty five point four",
            },
        ],
    ),
):
    results = {"item_id": item_id, "item": item}
    return results

Когда вы это сделаете, примеры станут частью внутренней JSON Schema для этих данных тела.

Тем не менее, на момент написания этого текста, Swagger UI, инструмент, отвечающий за показ интерфейса документации, не поддерживает отображение нескольких примеров для данных в JSON Schema. Но читайте ниже об обходном пути.

Специфичные для OpenAPI examples

Ещё до того, как JSON Schema поддержала examples, OpenAPI уже поддерживал другое поле, также называемое examples.

Эти специфичные для OpenAPI examples находятся в другом разделе спецификации OpenAPI. Они находятся в деталях для каждой операции пути, а не внутри каждой JSON Schema.

И Swagger UI уже довольно давно поддерживает это особое поле examples. Так что вы можете использовать его, чтобы показывать разные примеры в интерфейсе документации.

Форма этого специфичного для OpenAPI поля examples — это dict с несколькими примерами (вместо list), каждый с дополнительной информацией, которая также будет добавлена в OpenAPI.

Это не помещается внутрь каждой JSON Schema, содержащейся в OpenAPI, это помещается снаружи, непосредственно в операцию пути.

Использование параметра openapi_examples

Вы можете объявить специфичные для OpenAPI examples в FastAPI с помощью параметра openapi_examples для:

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

Ключи dict идентифицируют каждый пример, а каждое значение — это другой dict.

Каждый конкретный dict примера в examples может содержать:

  • summary: Краткое описание для примера.
  • description: Длинное описание, которое может содержать текст Markdown.
  • value: Это фактический показанный пример, например dict.
  • externalValue: альтернатива value, URL, указывающий на пример. Хотя это может поддерживаться не таким большим количеством инструментов, как value.

Вы можете использовать это так:

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Annotated[
        Item,
        Body(
            openapi_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
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Item = Body(
        openapi_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

Примеры OpenAPI в интерфейсе документации

С добавленным openapi_examples в Body() страница /docs будет выглядеть так:

Технические детали

Совет

Если вы уже используете FastAPI версии 0.99.0 или выше, вы, вероятно, можете пропустить эти детали.

Они более актуальны для старых версий, до появления OpenAPI 3.1.0.

Вы можете считать это кратким уроком истории OpenAPI и JSON Schema. 🤓

Предупреждение

Это очень технические детали о стандартах JSON Schema и OpenAPI.

Если описанные выше идеи уже работают для вас, этого может быть достаточно, и вам, вероятно, не нужны эти детали, не стесняйтесь их пропустить.

До OpenAPI 3.1.0 OpenAPI использовал более старую и модифицированную версию JSON Schema.

В JSON Schema не было examples, поэтому OpenAPI добавил своё собственное поле example в свою модифицированную версию.

OpenAPI также добавил поля example и examples в другие части спецификации:

Примечание

Этот старый специфичный для OpenAPI параметр examples теперь называется openapi_examples начиная с FastAPI 0.103.0.

Поле examples в JSON Schema

Но затем JSON Schema добавила поле examples в новую версию спецификации.

И затем новый OpenAPI 3.1.0 был основан на последней версии (JSON Schema 2020-12), которая включала это новое поле examples.

И теперь это новое поле examples имеет приоритет над старым одиночным (и пользовательским) полем example, которое теперь устарело.

Это новое поле examples в JSON Schema — это просто list примеров, а не dict с дополнительными метаданными, как в других местах OpenAPI (описано выше).

Примечание

Даже после того, как OpenAPI 3.1.0 был выпущен с этой новой более простой интеграцией с JSON Schema, в течение некоторого времени Swagger UI, инструмент, который обеспечивает автоматическую документацию, не поддерживал OpenAPI 3.1.0 (он поддерживает начиная с версии 5.0.0 🎉).

Из-за этого версии FastAPI до 0.99.0 всё ещё использовали версии OpenAPI ниже 3.1.0.

Pydantic и FastAPI examples

Когда вы добавляете examples внутрь модели Pydantic, используя schema_extra или Field(examples=["something"]), этот пример добавляется в JSON Schema для этой модели Pydantic.

И эта JSON Schema модели Pydantic включается в OpenAPI вашего API, а затем используется в интерфейсе документации.

В версиях FastAPI до 0.99.0 (0.99.0 и выше используют более новый OpenAPI 3.1.0), когда вы использовали example или examples с любыми другими утилитами (Query(), Body() и т.д.), эти примеры не добавлялись в JSON Schema, описывающую эти данные (даже не в собственную версию JSON Schema от OpenAPI), они добавлялись непосредственно в объявление операции пути в 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 или выше, и всё станет гораздо проще, согласованнее и интуитивнее, и вам не нужно знать все эти исторические детали. 😎