Генерація і підтримка REST API документації сервісів системи

Сторінка технічної документації є баченням майбутньої реалізації, актуальність якого може бути застарілою.

Загальні положення

  • REST API документація ведеться в форматі OpenAPI Specification

  • Для Java застосунків REST API документація будується автоматично на базі відповідних Swagger анотації в коді

  • Для застосунків які не генерують автоматичну REST API документація, документація формується вручну і зберігається у Git репозиторії сервісу

  • При побудові master/main версії сервісу, формується REST API документація та автоматично вносяться зміни в загальну документацію проєкту (Antora документація)

  • Опис методів, параметрів та відповідей повинен містити розширену інформацію про їх використання

  • Всі методи повинні мати приклади відповідей які будуть максимально наближені до реальних

  • Правила авторизації описуються тільки ті, що реалізовані безпосередньо в сервісі

  • Додатково до правил авторизації сервісу повинно бути посилання на документацію Зовнішнього API-шлюзу операційної зони та Підсистеми управління міжсервісною взаємодією з описом перевірок прав доступу на всіх рівнях

  • В сервісах з автоматичною генерацією REST API документація розгортається додатково з самим сервісом

З переліком сервісів та їх REST API документацією можна ознайомитись на сторінці API документація Платформи

Автоматичне оновлення документації

rest api.drawio
Figure 1. Компонентна діаграма автоматичної публікації REST API документації

  • Файл з REST API документацією може генеруватися автоматично в build пайплайні сервісу чи зберігатися розробником в репозиторії сервісу

  • Файл зберігається в репозиторії сервісу за шляхом docs/<service-name>-swagger.yml, де <service-name> - назва сервісу

  • Для автоматичної генерації файлу використовуються maven plugin в build пайплайні сервісу

Деталі по вибору плагіну та параметрів його налаштування поза скоупом цього документу

  • Build пайплайн відповідальний за те щоб файл з REST API документацією був опублікований в репозиторій загальної документації проєкту (Antora документація)

  • Файл публікується репозиторій загальної документації проєкту за шляхом docs/ua/modules/arch/attachments/architecture/platform-api/services/<service-name>-swagger.yml, де <service-name> - назва сервісу

  • Генерація файлу та його публікація відбувається тільки при побудові master/main версії сервісу

  • Підключення конкретного файлу з REST API документацією для візуалізації на сторінці документації відбувається вручну 1 раз для кожного сервісу

Обсяг робіт

MVP

  • Створення REST API документації для сервісів, що не мають автогенерації

  • Ручна публікація REST API документації сервісів в загальну документацію проєкту

Full scope

  • Публікація REST API документації сервісів в загальну документацію проєкту автоматично при зміні в master/main гілці

  • Для сервісів, документація яких ведеться вручну, додати файл з REST API документацією в репозиторії сервісу

  • Розширений опис методів, параметрів та відповідей

  • Збагачення REST API документації прикладами відповідей

  • Розширений опис правил авторизації включно з посиланнями на відповідні сторінки Зовнішнього API-шлюзу операційної зони та Підсистеми управління міжсервісною взаємодією

Поза скоупом

  • Тестове оточення для викликів сервісів з документації

  • Загальний опис сервісу формується окремо від REST API документації

  • Вказання ліцензії сервісу (в загальний опис сервісу)