ArchMapДокументация

Добавить спецификацию OpenAPI сервиса

Примечание

Спецификация OpenAPI описывает HTTP API сервиса. У сервиса одна спецификация. Добавить её можно только сервису без компонентов, потому что у контейнера раздел OpenAPI собирает спецификации его компонентов.

Добавить спецификацию вручную#

Чтобы добавить спецификацию, выполните следующие действия:

  1. На странице сервиса в разделе OpenAPI нажмите + Добавить и выберите Вручную. Откроется окно спецификации в режиме правки.
  2. Вставьте текст спецификации в формате YAML или JSON. Справа появится её превью.
  3. Нажмите кнопку Сохранить. В разделе OpenAPI появится строка Спецификация.

Примечание

Невалидная спецификация тоже сохраняется, но превью не обновится, пока текст не станет корректным.

Получить спецификацию от агента#

Бета-версия

Документирование с помощью ИИ-агента пока работает в режиме бета-версии. Перед применением проверьте, что предлагает агент, а после применения при необходимости поправьте результат вручную.

Чтобы получить спецификацию от агента, выполните следующие действия:

  1. На странице сервиса в разделе OpenAPI нажмите + Добавить и выберите Через ИИ-агента. Откроется окно спецификации с промптом слева и полем для файла справа.
  2. Скопируйте промпт и запустите агента в папке репозитория сервиса. Агент найдёт спецификацию в репозитории или составит её по коду и положит файл в папку archmap-docs/.
  3. Перетащите файл спецификации в поле справа.
  4. Нажмите кнопку Применить.

Примечание

Если в репозитории уже есть файл спецификации, агент копирует его как есть, а не пересказывает.

Примечание

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

Изменить или удалить спецификацию#

Чтобы изменить спецификацию, выполните следующие действия:

  1. На странице сервиса в разделе OpenAPI нажмите Спецификация. Откроется окно спецификации.
  2. В шапке окна нажмите Изменить и выберите:
    • Вручную, чтобы поправить текст;
    • Через ИИ-агента, чтобы заменить спецификацию новой от агента.
  3. Внесите изменения и нажмите кнопку Сохранить (в окне агента кнопка называется Применить).

Примечание

Чтобы удалить спецификацию, в режиме Вручную очистите текст и сохраните.

Связать эндпоинт со схемой логики#

Чтобы связать эндпоинт спецификации со схемой логики, выполните следующие действия:

  1. Откройте схему логики, которая описывает обработку эндпоинта, и перейдите в правку (см. Написать схему логики операции или воркера).
  2. В поле Эндпоинт укажите метод и путь так же, как в спецификации (например, POST /orders).
  3. Нажмите кнопку Сохранить.

Примечание

Если у контейнера осталась собственная спецификация (например, она была задана до того, как у сервиса появились компоненты), в разделе OpenAPI появится предупреждение. Перенесите спецификацию компоненту кнопкой Распределить по детям.