fastapi/docs/uk/docs/tutorial/metadata.md

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

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

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

Ви можете встановити такі поля, які використовуються в специфікації OpenAPI та в автоматично згенерованих інтерфейсах документації 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	URL до умов використання API. Якщо вказано, має бути у форматі URL.
contact	dict	Інформація для контакту з опублікованим API. Може містити кілька полів. contact поля Параметр Тип Опис name str Ідентифікаційне ім'я контактної особи або організації. url str URL, що вказує на контактну інформацію. МАЄ бути у форматі URL. email str Адреса електронної пошти контактної особи або організації. МАЄ бути у форматі адреси електронної пошти.
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_py310.py hl[3:16, 19:32] *}

/// tip | Порада

У полі description можна використовувати Markdown, і він буде відображатися у результаті.

///

З цією конфігурацією автоматична документація API виглядатиме так:

Ідентифікатор ліцензії

З початку використання OpenAPI 3.1.0 та FastAPI 0.99.0 Ви також можете налаштувати license_info за допомогою identifier замість url.

Наприклад:

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

Метадані для тегів

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

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

Кожен словник може містити:

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

Створення метаданих для тегів

Спробуймо це на прикладі з тегами для users та items.

Створіть метадані для своїх тегів і передайте їх у параметр openapi_tags:

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

Зверніть увагу, що в описах можна використовувати Markdown, наприклад, "login" буде показано жирним шрифтом (login), а "fancy" буде показано курсивом (fancy).

/// tip | Порада

Вам не потрібно додавати метадані для всіх тегів, які Ви використовуєте.

///

Використовуйте свої теги

Використовуйте параметр tags зі своїми операціями шляху (і APIRouters), щоб призначити їх до різних тегів:

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

/// info | Інформація

Детальніше про теги читайте в розділі Конфігурація операції шляху{.internal-link target=_blank}.

///

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

Тепер, якщо Ви перевірите документацію, вона покаже всі додаткові метадані:

Порядок тегів

Порядок кожного словника метаданих тегу також визначає порядок відображення в інтерфейсі документації.

Наприклад, хоча users мав би йти після items в алфавітному порядку, він відображається перед ними, оскільки ми додали їхні метадані як перший словник у списку.

URL для OpenAPI

За замовчуванням схема OpenAPI надається за адресою /openapi.json.

Але Ви можете налаштувати це за допомогою параметра openapi_url.

Наприклад, щоб налаштувати його на /api/v1/openapi.json:

{* ../../docs_src/metadata/tutorial002_py310.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_py310.py hl[3] *}