Redoc, порталы документации, Confluence
↑ 1.6 Документация API: Swagger и OpenAPI · ← Предыдущая · → Следующая
Зачем это аналитику и PM
Файл в репозитории разработчик найдёт. Заказчик и соседняя команда ищут страницу. Нужно понимать, какая страница собрана из спецификации, а какая — рассказ, который сам по себе контрактом не является.
План темы
- где публиковать
- как держать документацию актуальной
Объяснение
Один и тот же файл OpenAPI можно показать по-разному. Swagger UI удобен, когда метод надо отправить. Redoc собирает из файла страницу для чтения: оглавление и метод на одном экране. Точную раскладку колонок сверьте со сборкой, её меняли. Лицензию Redoc и то, есть ли там пробный вызов, смотрите у продукта. Здесь это не утверждается.
Портал документации — сайт, куда выкладывают эту страницу плюс вводные: как получить допуск, какой стенд, как сообщать о сбое. Имя конкретного портала и его цена зависят от компании. Цифры берите из их договора, не из заметки.
Confluence (и любая вики) хорошо держит решения, глоссарий и ссылку на файл. Плохо заменяет сам файл: страница не проверяет, что поле всё ещё строка. Макросы и шаблоны у пространства есть. Их точные имена в вашей вики свои, чужие подписи не копируют.
Как вывеска и книга рецептов. Вывеска зовёт в нужную дверь. Рецепт — спецификация. Если рецепт переписали, а вывеска старая, гость закажет не то.
Как не разъехаться
Источник правды один: файл спецификации в том месте, где его меняют вместе с задачей. Страница Swagger UI или Redoc собирается из этого файла. В вики лежит ссылка и две фразы, зачем метод, а не вторая копия всех полей. Когда поле меняют, правят файл. Страница, собранная вручную, получает дату и имя задачи, иначе ей не верят.
Кто публикует, договариваются заранее. Аналитик может принести текст метода. Сборку страницы часто делает тот, у кого доступ к стенду. Оба смотрят один файл.
Примеры
Что положить в вики, не дублируя контракт:
Метод создания заказа
Спецификация: ссылка на файл OpenAPI в репозитории
Стенд для проверки: имя окружения, без ключа
Зачем: черновик заказа до оплаты
Не копировать сюда список полей. Он в файле.Нюансы и подводные камни
- Две страницы, вики и портал, разойдутся в первую же правку. Ссылку держите, копию полей нет.
- Красная вики «обновлено вчера» не значит, что файл тот же. Сверьте путь метода.
- Портал с пробным вызовом на боевой адрес опасен так же, как Swagger UI. Учебный стенд подписывают явно.
- Закрытый портал без доступа заказчика не заменяет короткую выжимку, если ему нельзя в репозиторий. Выжимка всё равно ссылается на версию файла.
Практика
Выберите один метод вашей или учебной спецификации. Напишите три строки для вики: зачем метод, где файл, какой стенд. Список полей в эти строки не копируйте.
Ожидаемый результат: по строкам понятно, куда идти за контрактом. Поля остаются в OpenAPI. Секрета и боевого ключа в тексте нет.
Вопросы с ответами
Redoc заменяет файл OpenAPI?
Нет. Это вид того же файла. Нет файла — нечего показывать, кроме ручного рассказа.
Почему не описать API целиком в Confluence?
Вики не проверяет схему и легко расходится с кодом. Она хороша для решения и ссылки. Контракт остаётся в спецификации.
Кто обновляет страницу?
Тот, кто меняет контракт, правит файл. Страница, которая собирается из файла, обновляется вместе с ним. Ручную копию полей не заводят.
Что публиковать наружу?
То, что можно показать без секретов: путь, поля, коды, как запросить учебный допуск. Боевые ключи и внутренние адреса не входят в пример.