OpenAPI

Специфікація OpenAPI, початково відома як Swagger - це специфікація машиночитабельних файлів з інтерфейсами, для опису, створення, використання і візуалізації REST веб сервісів.

Зручним інструментом для роботи з API є Postman. Redoc - open source візуалзіатор API, який ми використовуєо.

Приклади

• Jira
• Stripe
• Edra Postman
• Edra Redoc
• GIS Editor

Процес напсиання та Вимоги до API

0. API документація є частиною проекту зберігається в форматі postman в /docs/
1. REST Найменування API

GET /api-user/gis-dataset          - список
GET /api-user/gis-dataset/:id      - детальна інформація окремий елемент
POST /api-user/gis-dataset/:id     - збереження окремий елемент

2. Опис з прикладом виклику
3. Опис параметрів - query, params, headers
4. Приклади містять скорочену відповідь 1 елемент масиву, а не 200 рядків
5. Status code 200x, 400x, 500x
6. За необхідності можно дублювати приклади як окремі API
7. Додаємо build API в документацію відносно папки docs і сам файл postman.json http://edra.local.softpro.ua/docs/api/
8. Ніяких ключів і даних користувачів

# частина pipeline
- cd /data/softpro/server/$CI_PROJECT_NAME/docs
- p2o postman.json > $CI_PROJECT_NAME.yml
- redoc-cli build $CI_PROJECT_NAME.yml

- mkdir -p site/api
- mv redoc-static.html site/api/index.html
- cp postman.json site/postman.json

8. Core API розміщуємо https://docs.softpro.ua/core/
9. Також можна pipelien https://docs.softpro.ua/apidocs/

Опис параметрів

Повний перелік параметрів знаходиться у файлі route.js. Приклад заповнення параметрів:

Redoc

Для генерації документації на клієнті (для передперегляду) можна запустити команду redoc-cli build {filename}.

Для генерації документації на сервері не потрібно виконувати жодних команд. Вони виконуються автоматично при виконанні пушу на сервер. Для цього необхідно зробити коміт з тегом doc.

Postman

Для опису API необхідно зайти до робочого веб-середовища Postman через загальний аккаунт. Далі можна імпортувати файл як колекцію або створити її прямо на сайті Postman.