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 — качество.
Замечанию можно поставить статус Новый, Подтверждён, Ложное, Риск принят или Исправлено. Показать в коде переводит курсор на нужную строку.
Доступ к спецификации
| Видимость | Кто видит и правит |
|---|---|
| Личная | Только владелец и те, с кем поделились |
| Уровень продукта | Участники продукта правят, владельцы продукта управляют доступом |
| Публичная | Все в организации могут смотреть; правят участники продукта и те, кому выдан доступ |
Администраторы и владелец спецификации всегда управляют доступом. Спецификации из репозиториев относятся к продуктам репозитория; если продукта нет, доступ к ним такой же, как к репозиторию. Загруженная Без продукта может быть только Личная или Публичная.
Кнопка Поделиться в шапке редактора открывает Доступ к спецификации: там меняют видимость и продукт, а в блоке Доступ людям и командам выдают доступ человеку или команде с ролью Просмотр или Правка. Выдавать доступ могут владелец спецификации, владельцы продукта и администраторы.