Механізм генерації asciidoc Rest API документації
Компоненти повторного використання для генерації RestAPI документації.
Призначення
Компоненти можуть бути використані для автоматичної генерації в spring boot based додатках asciidoc RestAPI документації з використанням інформації про request/response payloads після запуску unit тестів.
Передумови для використання
-
Maven based project.
-
spring-mvc based Rest додаток.
-
Використання
org.springframework.test.web.servlet.MockMvcдля тестування Rest controller layer.
| Відсутність деяких передумов не виключає повну неможливість застосування механізму в цілому, а лише лімітує функціональність розширень, що можуть бути використані. |
Опис механізму
Механізм використовує виключно maven plugins як спосіб виконання будь-яких дій для генерації asciidoc RestAPI документації.
Опис Maven plugins lifecycle
| Зображено лише основні кроки під час генерації RestAPI asciidoc. Кроки по переміщенню та видаленню файлів під час генерації не зображені на діаграмі. Більш детальна інформація в описі реалізації. |
Основні кроки:
-
Запуск spring boot application для отримання робочого RestAPI endpoints.
-
Отримання swagger документу по робочому RestAPI endpoints.
-
Генерація RestAPI asciidoc документації.
Структура файлів
-
RestAPI документація знаходиться в
docs/modules/<module_name>/pages/rest-api. Цей каталог буде використовуватись як базовий для генерації коду та зчитування includes та snippets. -
Код розширень документації повинен знаходитись в
rest-api-includes. Під час генерації Rest API asciidoc документу аналізується наявність include документів та snippets файлів. На основі цього відбувається включення цієї інформації в згенерований документ (includeasciidoc інструкція). Детальний опис структуриrest-api-includes. -
Сгенерований код документації буде знаходидись в каталозі rest-api-generated.