tiangolo.fastapi/docs/ru/docs/tutorial/schema-extra-example.md

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

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

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

Pydantic schema_extra

Вы можете объявить ключ example для модели Pydantic, используя класс Config и переменную schema_extra, как описано в Pydantic документации: Настройка схемы:

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

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

/// tip | Подсказка

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

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

///

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

При использовании Field() с моделями Pydantic, вы также можете объявлять дополнительную информацию для JSON Schema, передавая любые другие произвольные аргументы в функцию.

Вы можете использовать это, чтобы добавить аргумент example для каждого поля:

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

/// warning | Внимание

Имейте в виду, что эти дополнительные переданные аргументы не добавляют никакой валидации, только дополнительную информацию для документации.

///

Использование example и examples в OpenAPI

При использовании любой из этих функций:

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

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

Параметр Body с аргументом example

Здесь мы передаём аргумент example, как пример данных ожидаемых в параметре Body():

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

Аргумент "example" в UI документации

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

Body с аргументом examples

В качестве альтернативы одному аргументу example, вы можете передавать examples используя тип данных dict с несколькими примерами, каждый из которых содержит дополнительную информацию, которая также будет добавлена в OpenAPI.

Ключи dict указывают на каждый пример, а значения для каждого из них - на еще один тип dict с дополнительной информацией.

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

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

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

Аргумент "examples" в UI документации

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

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

/// warning | Внимание

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

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

///

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

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

Поля example как такового не существует в стандартах JSON Schema. В последних версиях JSON-схемы определено поле examples, но OpenAPI 3.0.3 основан на более старой версии JSON-схемы, которая не имела поля examples.

Таким образом, OpenAPI 3.0.3 определяет своё собственное поле example для модифицированной версии JSON Schema, которую он использует чтобы достичь той же цели (однако это именно поле example, а не examples), и именно это используется API в UI документации (с интеграцией Swagger UI).

Итак, хотя поле example не является частью JSON-схемы, оно является частью настраиваемой версии JSON-схемы в OpenAPI, и именно это поле будет использоваться в UI документации.

Однако, когда вы используете поле example или examples с любой другой функцией (Query(), Body(), и т.д.), эти примеры не добавляются в JSON-схему, которая описывает эти данные (даже в собственную версию JSON-схемы OpenAPI), они добавляются непосредственно в объявление операции пути в OpenAPI (вне частей OpenAPI, которые используют JSON-схему).

Для функций Path(), Query(), Header(), и Cookie(), аргументы example или examples добавляются в определение OpenAPI, к объекту Parameter Object (в спецификации).

И для функций Body(), File() и Form() аргументы example или examples аналогично добавляются в определение OpenAPI, к объекту Request Body Object, в поле content в объекте Media Type Object (в спецификации).

С другой стороны, существует более новая версия OpenAPI: 3.1.0, недавно выпущенная. Она основана на последней версии JSON-схемы и большинство модификаций из OpenAPI JSON-схемы удалены в обмен на новые возможности из последней версии JSON-схемы, так что все эти мелкие отличия устранены. Тем не менее, Swagger UI в настоящее время не поддерживает OpenAPI 3.1.0, поэтому пока лучше продолжать использовать вышеупомянутые методы.