# URL-адреса метаданных и документации { #metadata-and-docs-urls }

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

## Метаданные для API { #metadata-for-api }

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

| Параметр | Тип | Описание |
|------------|------|-------------|
| `title` | `str` | Заголовок API. |
| `summary` | `str` | Краткое резюме API. <small>Доступно начиная с OpenAPI 3.1.0, FastAPI 0.99.0.</small> |
| `description` | `str` | Краткое описание API. Может быть использован Markdown. |
| `version` | `string` | Версия API. Версия вашего собственного приложения, а не OpenAPI. К примеру `2.5.0`. |
| `terms_of_service` | `str` | Ссылка к условиям пользования API. Если указано, то это должен быть URL-адрес. |
| `contact` | `dict` | Контактная информация для открытого API. Может содержать несколько полей. <details><summary>поля <code>contact</code></summary><table><thead><tr><th>Параметр</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td>Идентификационное имя контактного лица/организации.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>URL указывающий на контактную информацию. ДОЛЖЕН быть в формате URL.</td></tr><tr><td><code>email</code></td><td><code>str</code></td><td>Email адрес контактного лица/организации. ДОЛЖЕН быть в формате email адреса.</td></tr></tbody></table></details> |
| `license_info` | `dict` | Информация о лицензии открытого API. Может содержать несколько полей. <details><summary>поля <code>license_info</code></summary><table><thead><tr><th>Параметр</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>ОБЯЗАТЕЛЬНО</strong> (если установлен параметр <code>license_info</code>). Название лицензии, используемой для API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>Выражение лицензии <a href="https://spdx.org/licenses/" class="external-link" target="_blank">SPDX</a> для API. Поле <code>identifier</code> взаимоисключающее с полем <code>url</code>. <small>Доступно начиная с OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>URL, указывающий на лицензию, используемую для API. ДОЛЖЕН быть в формате URL.</td></tr></tbody></table></details> |

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

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

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

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

///

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

<img src="/img/tutorial/metadata/image01.png">

## Идентификатор лицензии { #license-identifier }

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

К примеру:

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

## Метаданные для тегов { #metadata-for-tags }

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

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

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

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

### Создание метаданных для тегов { #create-metadata-for-tags }

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

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

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

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

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

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

///

### Используйте собственные теги { #use-your-tags }

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

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

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

Узнайте больше о тегах в [Конфигурации операции пути](path-operation-configuration.md#tags){.internal-link target=_blank}.

///

### Проверьте документацию { #check-the-docs }

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

<img src="/img/tutorial/metadata/image02.png">

### Порядок расположения тегов { #order-of-tags }

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

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

## URL-адрес OpenAPI { #openapi-url }

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

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

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

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

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

## URL-адреса документации { #docs-urls }

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

* **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_py39.py hl[3] *}
