Swagger является одним из языков описания программного интерфейса, API DL. Термин API нам уже встречался здесь. Термин DL означает Description Language, т.е. язык описания. Язык описания интерфейса позволяет создавать спецификации интерфейса, т.е. документацию по типам данных, хранящимся на сервере и функциям, к которым можно обращаться для работы с данными: получения, отправки, удаления и т.д.
Для создания такой документации не нужно изучать программный код, за нас это сделает программа, с использованием кода клиентской или серверной части программного обеспечения. Формат спецификации, создаваемый программой Swagger, принят в качестве стандарта для описания интерфейса программного обеспечения, использующего архитектурный стиль REST для передачи данных.
Этот стандарт называется Open API. Компания-разработчик Swagger передала этот способ описания взаимодействия программ с клиент-серверной архитектурой с целью унификации способа описания интерфейса, одинаково понятного для человека и компьютерных систем.
API DL позволяет не только генерировать спецификацию клиентской части или документацию сервера на основе программного кода, но и наоборот, генерировать программный код на основе спецификации. При подходе API Design First вначале проектируется интерфейс, затем его отдают разработчику. При подходе Code First вначале пишется код, на основе бизнес-плана, затем генерируется документация.
Если у нас есть программный код серверной части приложения и мы хотим получить по нему документацию, то нужно использовать инструмент Swagger-core, а для генерации программного кода на основе документации использовать инструмент Swagger Codegen.
Большим преимуществом использования "умной" Swagger-документации является возможность поддерживать документацию в актуальном состоянии. Бывают случаи, когда программе уже много лет и какие-то части документации потерялись или код давно изменили, а документация осталась прежней и не соответствует коду.
Теперь давайте рассмотрим, как тестировщики могут использовать этот инструмент. Если разработчики программного продукта уже получили документацию с помощью программы Swagger, то с помощью инструмента Swagger UI можно получить красивый интерфейс, описывающий функции для обращений к серверу с помощью запросов, например, в программе Postman.
Это справочная информация, наглядно показывающая, как должен выглядеть запрос и ответ на него, какие данные нужно передать и каковы типы этих данных:
В программе Postman, для удобства работы, также появилась возможность интегрировать документацию из программы Swagger. Postman при этом сгенерирует коллекцию запросов по спецификации.
Остальные нюансы работы рассмотрим в следующих публикациях, по мере необходимости.
Если понравилось, ставьте лайк. Если есть вопросы, пишите в комментариях. В закрепленном сообщении видео для подписчиков.
