Страница документации API — это портал для разработчиков: справочник по OpenAPI, Markdown-руководства рядом с ним и переключатель версий. Всё живёт внутри версии, а версия публикуется одним снимком. В этой инструкции — создание страницы, работа с версиями и публикация. Загрузка OpenAPI-документа описана в разделе , руководства — в разделе .

Войдите по адресу , откройте свою команду и нажмите . Выберите тип , укажите название и адрес и подтвердите. Вы попадёте на вкладку .

У каждой версии свои руководства и свой OpenAPI-контракт. Нажмите и заполните:

• Slug версии — например v1. Он станет адресом для читателей /v/{slug}/ и замораживается, как только версия хотя бы раз опубликована: интеграторы хранят его в закладках и CI-конфигах.
• Отображаемое имя — показывается в переключателе версий. Можно менять в любой момент.
• Описание — по желанию.

В шапке видно, сколько версий допускает ваш тариф. Одна из версий — основная, на неё попадают читатели; выбрать её можно пунктом в меню версии.

Открыв версию, вы увидите её разделы:

• Обзор
  — состояние, ссылки для читателей и настройки версии.
• Публикация
  — что выйдет со следующим снимком и кнопки публикации.
• Руководства
  — Markdown-страницы рядом со справочником.
• Импорт спецификации
  — все загруженные OpenAPI-документы с отчётами проверки.
• История
  — все собранные публикации с возможностью отката.
• Удалённый источник
  — опрос OpenAPI-документа из репозитория или по URL.

Руководства и контракт выходят вместе одним неизменяемым снимком — «опубликовать одно руководство» нельзя. На вкладке перечислено, что будет опубликовано: сколько руководств включено и какой импорт спецификации выбран, а также структурные изменения относительно текущего контракта. Дальше:

• Опубликовать
  — зелёная кнопка с именем версии собирает снимок и выкладывает его. У каждой публикации свой номер, и номера только растут.
• Запланировать
  — снимок собирается сразу и выходит в назначенное время, так что выйдет ровно то, что вы проверили. Правки после планирования в него не попадут — отмените и запланируйте снова, чтобы включить их.
• Снять с публикации
  — скрывает версию с сайта.
  Опубликовать снова
  собирает свежий снимок из текущей работы; «Восстановить из архива» возвращает ровно то, что было на сайте, новой публикацией.

После новых правок у версии появляются неопубликованные изменения: читатели видят текущую публикацию до следующей.

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

В → можно разрешить читателям отправлять настоящие запросы к вашему API прямо из справочника. Запросы идут из их браузера на ваши серверы — введённые ключи до нас не доходят. Список servers в вашем OpenAPI-документе решает, какие адреса доступны; предлагаются только https-адреса. По умолчанию выключено; только GET, если вы не разрешите также POST, PUT, PATCH и DELETE — перед каждым таким запросом читателя просят подтвердить.