Как ускорить тестирование приложения с помощью OpenAPI-спецификаций

OpenAPI — универсальный инструмент, который используется для решения задач разработчиков и аналитиков. Но и тестировщики могут применить его для повышения эффективности работы. QA Team Leader команды тестирования Группы «Иннотех» Андрей Терешин рассказал, как можно использовать OpenAPI для тестирования.

Андрей Терешин

QA Team Leader команды тестирования Группы «Иннотех»

Что такое OpenAPI?

OpenAPI спецификации — это набор инструкций и инструментов, который описывает взаимодействие для Rest-приложений. Если по-простому, то это экосистема со множеством инструментов, предоставляющая интерфейс между front-end-системами, кодом библиотек низкого уровня и коммерческими решениями в виде API. Она не зависит от языков программирования и может использоваться на большом количестве проектов. OpenAPI рассматривается как универсальный интерфейс для пользователей (клиентов) по взаимодействию с сервисами (серверами).

OpenAPI-спецификацию часто можно встретить в формате JSON для определения «объектов», «массивов», «свойств», «полей» и так далее. Но также используется и формат YAML.

Пример:

YAML

			zoo:
  animal: giraffe
  bird: eagle
		

JSON

			{
    " zoo ": {
        "animal": " giraffe Bear",
        "bird": " eagle "
    }
}
		

Часто можно встретить термины Swagger и OpenAPI в одном контексте, но было бы правильно их разделить. Если простыми словами описать различия, то Swagger — это коммерческий продукт и спецификация версии 2.0, и он относится к инструментам API. А OpenAPI — это бесплатная спецификация Swagger версии 3.0 и выше. Кстати, Swagger было первичным оригинальным названием OpenAPI.

OpenAPI может быть использована разработчиками для обеспечения согласованности/стандартизации разработки REST API. Она также является хорошим документом для описания реализованной API для тестирования. Условно, у вас будет описан endpoint с типом запроса Post с полями А и В.

Дополнительно в проекте может быть настроена генерация клиента или сервера из OpenAPI-спецификации для команд бекэнда или фронтенда, таким образом, можно проводить разработку или тестирование без ожидания друг друга.

Основные отличия OpenAPI 2.0 от 3.0

Одним из преимуществ перехода с 2.0 на 3.0 — сокращение спецификации из-за объединения данных. То есть спецификация реструктурирована для увеличения возможностей повторного использования OpenAPI 3.0, которая представляет реорганизованную структуру инструкций для удобства переиспользования API. Также такие структуры, как securityDefinitions, definitions, parameters и response, были перемещены в components:

Таким образом, из рисунка выше можно увидеть объединение:

1. host, basePath в hosts;
2. definitions, parameters, responses в components.

Что такое components в версии 3.0?  Components включает в себя объект компонентов, который содержит повторно используемые объекты в спецификации, такие как параметры (parameters), ответы (response), тела запроса (body request), ссылки (links), схемы безопасности (security schemes) и схемы (schemes), заголовки (headers) и обратные вызовы (callbacks).

Подробнее о различиях можно прочитать тут.

Как пользоваться OpenAPI в тестировании

Спецификации можно написать в редакторе Swagger Editor. Но спецификацию OpenAPI можно генерировать на основе Swagger-annotation автоматически.

Для удобства визуализации часто применяется Swagger Editor или Swagger UI. Чтобы воспользоваться Swagger Editor, можно спуллить образ docker:

			docker pull swaggerapi/swagger-editor
		

Далее запустить в контейнере локально:

			docker run -d -p 80:8080 swaggerapi/swagger-editor 
		

Если не хочется заморачиваться с консолью, можно воспользоваться online-версией.

При написании спецификации редактор Swagger Editor в режиме реального времени проверяет инструкцию на предмет её валидности. Таким образом, можно быстро исправить ошибку.

Пример тестовой OpenAPI-спецификации в форматах JSON и YAML.

В редакторе Swagger можно выполнить следующие операции:

1. Конвертировать спецификацию из формата JSON в YAML или из YAML в JSON.
2. Конвертировать OpenAPI 2.0 в 3.0 (Edit->Convert to OpenAPI 3) в случае повышения версии.
3. Сгенерировать Server на основе спецификации (spring, go-server, kotlin-server и другие) или Client на основе спецификации (java, go и другие) для разработки или тестирования приложения.
4. Отправить тестовый запрос на endpoint для проверки его работы.

Мне больше нравится отлаживаться с помощью Postman и OpenAPI. Они позволяют быстро импортировать коллекцию запросов. Для этого достаточно скопировать спеку в формате JSON или YAML и импортировать в postman:

Спецификация OpenAPI не только визуализирует контроллеры в тестируемом API, но также помогает в написании автотестов. Например, можно сгенерировать клиента на основе шаблонизатора mustache, который с помощью шаблонов убирает ограничения на используемый язык в генерируемых файлах клиента.

Плюсы и минусы использования шаблонизатора mustache:

Плюсы: можно выделить плюс в стандартизации кода тестов, что позволит поддерживать их просто и быстро. Данный подход поможет командам, у которых имеется несколько проектов на поддержке.

Минусы: при использовании шаблонизатора есть минус сгенерённого кода — это его поддержка. Чтобы изменить или поправить тест, потребуется изменять шаблон.

Пример реализации генерации API тестов на основе OpenAPI спецификаций можно посмотреть тут с Java + RestAssured + Maven/Gradle.

А что дальше?

Как можно увидеть, спецификации OpenAPI и инструменты Swagger Editor/Swagger являются неотъемлемыми атрибутами в процессе тестирования API. Я дал только ограниченные примеры их использования. Но гибкие возможности OpenAPI позволяют существенно автоматизировать рутинные процессы тестирования и сделать жизнь тестировщика проще.