Використання OpenAPI в тестуванні

OpenAPI (раніше відомий як Swagger) є стандартом для опису API інтерфейсів та їх використання в тестуванні. OpenAPI дозволяє описати всі можливості та обмеження API (доступні операції, параметри, формати відповіді). Опис використовується для автоматизації тестів АРІ та для забезпечення взаємної сумісності між різними інструментами та сервісами.

Описувати API можна у форматах YAML або JSON. Загальна структура OpenAPI в форматі YAML має наступний вигляд:

Для  формата YAML важливо робити правильні відступи, так як це впливає на структуру документа. Також у форматі YAML використовуються знаки тире для опису списку значень (наприклад, список серверів) та двокрапки для опису ключів та їх значень.

У  форматі JSON цей код виглядатиме наступним чином:

Базова структура складається із 8 об’єктів:

• номеру версії OpenAPI, яка використовується у документації;
• загальної інформації про API (назва, опис, версія) – об’єкт info;
• списку серверів (servers), на яких можна запускати АРІ (у нашому випадку, для прикладу наведеному на скріншоті вище, він один – https://api.example.com/v1);
• опису шляхів (paths) до ресурсів АРІ та методів, які можна використовувати для взаємодії з цими ресурсами. У нашому випадку є один шлях до ресурсу /users, який можна використовувати для отримання списку користувачів (метод GET) та створення нового користувача (метод POST). Кожен метод має опис, який включає заголовок запиту (summary), список відповідей (responses) та інформацію про те, як взіємодіяти з тілом запиту (requestBody);
• компонентів (components) такі як схеми, параметри запиту, відповідей тощо. У нашому прикладі є дві схеми: User та NewUser. Схема User містить три властивості – id, name, email, кожна з яких має свій тип даних. Ці схеми можна перевикористати у різних місцях специфікації, замість того, щоб кожного разу копіювати їхні описи.

Також є такі об’єкти, як security, tags, externalDocs, проте в нашому прикладі вони відсутні.

Документація для API є колосально важливим елементом для розробки, тестування та використання API. Давайте розглянемо чому:

1. Документація допомагає розуміти, як працює АРІ та як взаємодіяти з ним. Вона надає інформацію про доступні ендпоінти, параметри запитів, формати даних, коди помилок тощо. Це зменшує час, необхідний для розробки та тестування програмного забезпечення, яке використовує АРІ.
2. Документація зменшує кількість помилок під час взаємодії з АРІ. Користувачі можуть перевіряти правильність запитів та відповідей АРІ, що зменшує кількість помилок та пришвидшує швидкість розробки.
3. Документація робить АРІ більш доступним. Завдяки добре написаній документації розробники можуть швидко інтегрувати його у свої проєкти, що збільшує кількість користувачів.
4. Документація допомагає зберігати сумісність між версіями АРІ. Якщо в документації вказано, які поля та параметри можна використовувати в АРІ, то зміни в нових версіях будуть менш імовірними та легше контролюватись.

Основні функціональні можливості OpenAPI включають:

1. Опис методів АРІ: OpenAPI дозволяє описувати методи, що підтримуються АРІ (GET, POST, PUT, DELETE тощо), включаючи типи запитів та відповідей, що очікуються від АРІ.
2. Документація АРІ: на основі опису АРІ, OpenAPI має функцію автоматичного створення документації, що описує методи, які використовуються, а також типи запитів та відповідей.
3. Перевірка валідності: OpenAPI дозволяє перевіряти валідність запитів до АРІ, що допомагає запобігти помилкам та забезпечує більшу стабільність системи.
4. Підтримка різних форматів: дозволяє описувати АРІ у форматах JSON та YAML.
5. Генерація клієнтських бібліотек: автоматична генерація клієнтських бібліотек для різних мов програмування на основі специфікації АРІ.
6. Підтримка тестування АРІ: OpenAPI дозволяє автоматично генерувати тестові запити для АРІ, що допомагає перевіряти його функціональність.
7. Підтримка автоматичної документації: автоматичне створення документації АРІ на основі специфікації.
8. Сумісність з іншими інструментами: OpenAPI інтегрується з багатьма іншими інструментами, такими як Swagger UI, який дозволяє взаємодіяти з АРІ в браузері, а також з різними системами автоматичного тестування та CI/CD.

Ці функціональні можливості роблять OpenAPI потужним інструментом для опису та розробки API.

У тестуванні, OpenAPI може використовуватись для автоматичної генерації тестових скриптів згідно з описом АРІ в специфікації. Такі тестові скрипти можуть перевіряти, чи працює АРІ правильно та відповідає специфікації. Також OpenAPI  може використовуватись для автоматизованої генерації документації АРІ, яка буде корисною для розробників, що працюють з АРІ, а також тестувальників, які можуть використовувати документацію для розуміння того, як АРІ повинно працювати.

Найкращий спосіб вивчити OpenAPI – це практичний підхід. Певні інструменти дозволяють редагувати специфікації OpenAPI, а потім генерувати API документацію. Для зручності візуалізації часто використовується Swagger Editor чи Swagger UI. 

SwaggerUI – це інструмент, який аналізує визначення API для створення документації. SwaggerUI має браузерний редактор (показано нижче). Якщо є бажання поекспериментувати з редактором SwaggerUI, зробити це можна тут: https://editor.swagger.io/

Редактор дозволяє:

1. Конвертувати специфікацію із JSON в YAML та з YAML в JSON.
2. Конвертувати OpenAPI 2.0 у 3.0 (Edit->Convert to OpenAPI 3) у випадку підвищення версії.
3. Згенерувати Server на основі специфікації або Client на основі специфікації для розробки або тестування програми.
4. Надіслати тестовий запит на endpoint для перевірки його роботи.

Специфікація Swagger Petstore є прикладом документа OpenAPI.

На лівій бічній панелі видно специфікацію OpenAPI у форматі YAML. Щоразу, коли ви вносите зміни до специфікації, ці зміни генерують нову документацію на правій бічній панелі. Права бічна панель – це документ Swagger, створений безпосередньо зі специфікації OpenAPI (ліва бічна панель). Наприклад, зміна опису шляху призводить до оновлення документа Swagger з новими змінами.

Якщо подивитися на специфікацію OpenAPI Swagger зліва, то можна побачити всі розділи, описані в цій статті блогу, включаючи openapi, info, сервери, шляхи, компоненти, теги тощо. Ознайомившись із Swagger Petstore, можливо вставити специфікацію іншого API у Swagger Editor, щоб побачити, як його інформація відображається у SwaggerUI.

Swagger видає помилку, при відхиленні від структури OpenAPI або введенні чогось невірно. Обробка помилок у Swagger підкріплює концепцію, що необхідно дотримуватися формату OpenAPI для коректного відображення документації. 

Для перегляду деталей можна розгорнути АРІ у редакторі. У нашому прикладі це GET /pet/{petId}

Для операції GET /pet/{petId} можна побачити що:

• responses: зі значенням «200» для успішної операції;
• тип медіа додаток/json;
• дані для кожного з елементів повертаються в масиві.

Крім того, ви можете відправити запит за допомогою кнопки «Try it out», щоб протестувати API.

OpenAPI специфікації та інструменти Swagger Editor/Swagger є необхідними елементами для тестування API. У статті розглянуто лише деякі приклади використання цих інструментів, проте OpenAPI забезпечує гнучкі можливості, що дозволяють значно автоматизувати рутинні процеси тестування та полегшити життя тестувальників.