fastapi/docs/ru/docs/tutorial/metadata.md

URL-адреса метаданных и документации

Вы можете настроить несколько конфигураций метаданных в вашем FastAPI приложении.

Метаданные для API

Вы можете задать следующие поля, которые используются в спецификации OpenAPI и в UI автоматической документации API:

Параметр	Тип	Описание
title	str	Заголовок API.
summary	str	Краткое резюме API. Доступно начиная с OpenAPI 3.1.0, FastAPI 0.99.0.
description	str	Краткое описание API. Может быть использован Markdown.
version	string	Версия API. Версия вашего собственного приложения, а не OpenAPI. К примеру 2.5.0.
terms_of_service	str	Ссылка к условиям пользования API. Если указано, то это должен быть URL-адрес.
contact	dict	Контактная информация для открытого API. Может содержать несколько полей. поля contact Параметр Тип Описание name str Идентификационное имя контактного лица/организации. url str URL указывающий на контактную информацию. ДОЛЖЕН быть в формате URL. email str Email адрес контактного лица/организации. ДОЛЖЕН быть в формате email адреса.
license_info	dict	Информация о лицензии открытого API. Может содержать несколько полей. поля license_info Параметр Тип Описание name str ОБЯЗАТЕЛЬНО (если установлен параметр license_info). Название лицензии, используемой для API. identifier str Выражение лицензии SPDX для API. Поле identifier взаимоисключающее с полем url. Доступно начиная с OpenAPI 3.1.0, FastAPI 0.99.0. url str URL, указывающий на лицензию, используемую для API. ДОЛЖЕН быть в формате URL.

Вы можете задать их следующим образом:

{* ../../docs_src/metadata/tutorial001.py hl[3:16, 19:32] *}

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

Вы можете использовать Markdown в поле description, и оно будет отображено в выводе.

///

С этой конфигурацией автоматическая документация API будет выглядеть так:

Идентификатор лицензии

Начиная с OpenAPI 3.1.0 и FastAPI 0.99.0, вы также можете задать license_info с помощью identifier вместо url.

К примеру:

{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}

Метаданные для тегов

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

Он принимает список, содержащий один словарь для каждого тега.

Каждый словарь может содержать в себе:

• name (обязательно): str-значение с тем же именем тега, которое вы используете в параметре tags в ваших операциях пути и APIRouterах.
• description: str-значение с кратким описанием для тега. Может содержать Markdown и будет отображаться в UI документации.
• externalDocs: dict-значение описывающее внешнюю документацию. Включает в себя:
  • description: str-значение с кратким описанием для внешней документации.
  • url (обязательно): str-значение с URL-адресом для внешней документации.

Создание метаданных для тегов

Давайте попробуем сделать это на примере с тегами для users и items.

Создайте метаданные для ваших тегов и передайте их в параметре openapi_tags:

{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}

Помните, что вы можете использовать Markdown внутри описания, к примеру "login" будет отображен жирным шрифтом (login) и "fancy" будет отображаться курсивом (fancy).

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

Вам необязательно добавлять метаданные для всех используемых тегов

///

Используйте собственные теги

Используйте параметр tags с вашими операциями пути (и APIRouterами), чтобы присвоить им различные теги:

{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}

/// info | Дополнительная информация

Узнайте больше о тегах в Конфигурации операции пути{.internal-link target=_blank}.

///

Проверьте документацию

Теперь, если вы проверите документацию, вы увидите всю дополнительную информацию:

Порядок расположения тегов

Порядок расположения словарей метаданных для каждого тега определяет также порядок, отображаемый в UI документации.

К примеру, несмотря на то, что users будут идти после items в алфавитном порядке, они отображаются раньше, потому что мы добавляем свои метаданные в качестве первого словаря в списке.

URL-адрес OpenAPI

По умолчанию схема OpenAPI отображена по адресу /openapi.json.

Но вы можете изменить это с помощью параметра openapi_url.

К примеру, чтобы задать её отображение по адресу /api/v1/openapi.json:

{* ../../docs_src/metadata/tutorial002.py hl[3] *}

Если вы хотите отключить схему OpenAPI полностью, вы можете задать openapi_url=None, это также отключит пользовательские интерфейсы документации, которые её используют.

URL-адреса документации

Вы можете изменить конфигурацию двух пользовательских интерфейсов документации, которые включены:

• Swagger UI: отображаемый по адресу /docs.
  • Вы можете задать его URL с помощью параметра docs_url.
  • Вы можете отключить это с помощью настройки docs_url=None.
• ReDoc: отображаемый по адресу /redoc.
  • Вы можете задать его URL с помощью параметра redoc_url.
  • Вы можете отключить это с помощью настройки redoc_url=None.

К примеру, чтобы задать отображение Swagger UI по адресу /documentation и отключить ReDoc:

{* ../../docs_src/metadata/tutorial003.py hl[3] *}