Swagger

Swagger - это инструмент для описания, и тестирования HTTP API (Что это?). Ознакомиться с продуктом подробнее можно на официальном сайте. Изначально разрабатывался для работы с протоколом SOAP (Что это? википедия), но потом стал использоваться и для работы с любым HTTP API. Наше публичное API использует Swagger и спецификацию Open API для описания возможностей взаимодействия, что очень удобно. 

Если говорит простыми словами, то с помощью Swagger мы можем описать как работает наше API не просто текстом, а красиво структурировать, предоставить примеры использования, с возможностью интерактивной работы с ними. Прямо в интерфейсе получившейся документации можно понажимать на кнопки и посмотреть результат работы того или иного метода, с полным описанием формата взаимодействия. 

Зачем это нужно? 

К сожалению большинство HTTP API так устроено, что снаружи совершенно невозможно понять есть оно вообще и работает ли оно, если нет документации. Формат передаваемых данных и сами данные разработчик API волен обратабывать так как ему заблагорассудится. И для того чтобы разобраться, в самых запущенных случаях, приходится прибегать к реверс-инжинирингу. Когда мы находим какую-то часть приложения или другое приложение которая уже работает с этим API и пытаемся понять как оно это делает. Очень сильно в этом деле помогает наличие исходных кодов.

Swagger помогает решить эту проблему, во первых тем, что многие фреймворки поддерживают работу с ним из коробки, и могут сгенерировать swagger-документацию автоматически. Так и в целом тем, что устроен достаточно удобно и позволяет сформировать действительно красивую и удобную документацию без особых трудозатрат.

Да и в целом стоит научиться работать с таким вариантом документации, хотя бы потому, что он является в своем роде стандартом, и многие публичные сервисы предоставляют интеграционную документацию в формате Open API (Swagger).

Яркий пример такой документации  можно увидеть и на сайте самого Swagger. Перейдя по ссылке. 

 

Мы видим что документация удобна тем, что позволяет заполнить значения параметров, нажать на кнопку "Try it out" и посмотреть в каком формате целевому приложению будет передан запрос и какой будет получен ответ.