Разделы документации

API

Как Archepelag находит эндпоинты и спецификации OpenAPI в репозиториях и как работать со спецификациями в «Управлении API».

Где искать API

МестоЧто там
Вкладка API репозиторияЭндпоинты и спецификации одной ветки, история анализов
Раздел РесурсыЭндпоинты и спецификации всех репозиториев, запуск обнаружения по организации
Управление API (группа «Студии» в Workspace)Список спецификаций, редактор, проверки, сравнение версий, доступ

«Управление API» появляется в меню, только если в установке включено обнаружение API.

Вкладка API репозитория

Данные собирает анализ ветки — тот же, что строит стек репозитория, см. Анализ кода и стек. Он ищет три вида источников: маршруты в коде, файлы OpenAPI и Swagger, маршруты nginx.

Пока анализа не было, вкладка показывает экран API ещё не собрано с кнопкой Анализ ветки. Если анализ прошёл, но ничего не нашёл, появится API не найдено: можно Повторить анализ или Открыть Studio и загрузить спецификацию вручную. Если анализ упал — Анализ завершился ошибкой и кнопка Подробности с логом последнего прогона. Пока анализ идёт, вкладка обновится сама.

Когда данные есть, в шапке API Surface видно число эндпоинтов, спецификаций, источников и эндпоинтов без ревью. Кнопка Analyze запускает анализ заново, Open Studio открывает Studio в контексте репозитория. Строка Sources раскрывает, сколько эндпоинтов дал каждый источник.

РазделЧто показывает
EndpointsЭндпоинты ветки: поиск, фильтр по методу, карточка эндпоинта
SpecificationsНайденные OpenAPI и Swagger, число путей и покрытие кода спецификацией
ChangesСравнение кода со спецификацией; расхождения по каждой спецификации — в Specifications
HistoryПрогоны анализа ветки: статус, ветка, время, длительность

Если в ветке нет ни одной спецификации, раздел Specifications показывает No API specification detected и число эндпоинтов, найденных в коде.

Карточка эндпоинта

У каждого эндпоинта есть статус ревью: Новый, Подтверждён, Нужна проверка или Ложное. На вкладке Evidence видно, откуда он взялся (Код, Спека, Исходящий вызов) со ссылкой на строку в репозитории. Источник можно пометить ложным с причиной: Тестовый код, Пример, Мёртвый код, Сгенерированный код, Ошибка сканера или Другое. Метка Undocumented означает, что эндпоинта нет ни в одной спецификации.

Обнаружение по всей организации

В разделе Ресурсы кнопка Запустить обнаружение ставит в очередь анализ ветки по умолчанию для каждого активного репозитория. Репозитории, где с прошлого успешного анализа не было новых коммитов, пропускаются. Пока прогон идёт, рядом виден счётчик обработанных репозиториев.

Если ресурсов ещё нет, раздел показывает Ресурсов пока нет с той же кнопкой.

Управление API: список спецификаций

На стартовой странице три вкладки: Все API, Мои (загруженные вами) и Недавние (те, что вы открывали в этом браузере). Есть поиск по названию и репозиторию, фильтры по видимости и продукту. В колонке Проверка — Не проверена, Проверяется…, Без замечаний или число открытых замечаний.

Меню строки: Открыть, Сравнить с веткой (для спецификаций из репозитория), Проверить заново, Доступ и видимость (или Кто видит, если управлять доступом вы не можете) и Удалить из списка. Удалить можно только загруженную вручную спецификацию и только с правом управления; вместе с ней удаляются история правок и результаты проверок.

Кнопка Открыть спецификацию загружает новую:

  • Файл YAML / JSON — OpenAPI 3 или Swagger 2, до 10 MB; файл можно и перетащить на страницу.
  • По ссылке — файл скачивает ваш браузер, сервер по этому адресу не ходит.
  • Вставить код — текст спецификации целиком.

Перед открытием выберите Продукт и Кто видит. Если в Studio пока пусто, страница показывает Начните со спецификации API. Спецификации из репозиториев попадают в список после обнаружения API.

Редактор

ВкладкаЧто там
СпецификацияИсходный YAML или JSON с подсветкой ошибок
ГрафСвязи операций и схем
ДокументацияОперации и Схемы в читаемом виде
ИсторияРевизии, сравнение с текущей версией, тренд оценок
ИзмененияСравнение с той же спецификацией в другой ветке: ломающие и совместимые изменения

Правая панель: Обзор (метрики документа и итоговая оценка от A до F), Объекты (выбранный узел и что на него ссылается), Замечания, Правила и Инструменты (конвертация YAML ↔ JSON, Сохранить в инвентарь). Сохранить (или Ctrl+S) сохраняет текст, а прежняя версия уходит в ревизии; хранятся последние 50. Проверить сохраняет несохранённые правки и запускает две проверки: Vacuum — безопасность, Spectral — качество.

Замечанию можно поставить статус Новый, Подтверждён, Ложное, Риск принят или Исправлено. Показать в коде переводит курсор на нужную строку.

Доступ к спецификации

ВидимостьКто видит и правит
ЛичнаяТолько владелец и те, с кем поделились
Уровень продуктаУчастники продукта правят, владельцы продукта управляют доступом
ПубличнаяВсе в организации могут смотреть; правят участники продукта и те, кому выдан доступ

Администраторы и владелец спецификации всегда управляют доступом. Спецификации из репозиториев относятся к продуктам репозитория; если продукта нет, доступ к ним такой же, как к репозиторию. Загруженная Без продукта может быть только Личная или Публичная.

Кнопка Поделиться в шапке редактора открывает Доступ к спецификации: там меняют видимость и продукт, а в блоке Доступ людям и командам выдают доступ человеку или команде с ролью Просмотр или Правка. Выдавать доступ могут владелец спецификации, владельцы продукта и администраторы.