Swagger. Что это и как с ним работать

В предыдущем посте я рассказывал про посещение конференции и прослушивание различных выступлений, на тему OpenAPI и swagger в том числе. Плюс в принципе упоминал эти термины, когда рассказывал про синхронные интеграции.
Стоит посвятить этому инструменту отдельный пост и рассказать что это такое.

Swagger — набор инструментов для создания, документирования и тестирования RESTful API. Основой Swagger является формат OpenAPI, который позволяет описывать API на уровне спецификаций (ссылки без vpn не работают).

Для чего он вообще нужен и почему применяется на проектах?

➖Автоматическая генерация документации, понятной для людей и машин;
➖Обратный процесс - автоматическая генерация кода на основе документации с помощью Swagger Codegen;
➖Тестирование API. Предоставляет функционал аналогичный Postman, т.е. возможность вручную "подергать" методы;
➖Единый стандарт (OpenAPI) для совместимости между системами и командам.

Таким образом, это отличный инструмент который позволяет либо сгенерировать документацию на основе написанного кода (когда нет аналитиков, но какую-то документацию очень хочется иметь - вообще замечательно).
Либо, что более правильно, позволяет написать и описать спецификацию сервиса (все его методы, DTO, которые они используют). Такая документации получится более понятной и качественной, в ней можно каждый метод и каждый атрибут описать человеческим языком и даже можно (правда в очень урезанном виде) описать то, что метод делает. И уже на основании этой спецификации уже сгенерировать код.

Кроме того, что на проекте в принципе появляется документация, что само по себе уже отлично - становятся доступны различные подходы к разработке, которые позволяют оптимизировать процессы в командах и даже межкомандное взаимодействие. Например, если использовать подход Swagger First (Contract\API First, называется по-разному). Об это расскажу в следующем посте.

Также, те аналитики (и не только), кто работали на проектах, где есть и FE и BE - наверняка сталкивались с такой проблемой, что фронтендеры не могли приступать к своей части разработки, до тех пор, пока бэкенд не предоставит им контракт какого-нибудь, например, фронтального адаптера, с которым FE нужно интегрироваться в рамках доработки.
А это может быть долгая история, т.к. пока опишешь API, пока опишешь всю бизнесовую логику работы, пока пройдешь ревью и т.д. - фронтендеры устанут ждать. С помощью swagger'а же бэкенд-разработчики могут сначала описать API, опубликовать его и дальше продолжать описывать всю остальную часть, но при этом фронты уже могут приступать к работе и работать параллельно, что ускоряет процесс.

Ну и вообще нагрузить системных аналитиков, чтобы они сами написали спецификацию (и я считаю, что это правильно), выложили ее в репозитарий аналитики в гите и уже потом приступать к разработке сервиса, имея на руках ТЗ и спецификацию.
Единственное, что стоит отметить - спецификация != документация. Т.е. вы с помощью спецификации можете описать сервис, можете описать все его эндпоинты и методы - но вы должны отдельно описать еще в документации то, а как эти методы будут работать, т.е. их бизнес-логику. Потому что в рамках сваггера это хоть и реализуемо, но весьма сложно и не красиво.
Поэтому для каждого сервиса идеально иметь две части документации - одну, с описанием самого сервиса, всей его бизнес-логики и логики работы его методов; и вторую - спецификацию.

Рекомендую ознакомиться с этим инструментом, посмотреть на pet-проект и попытаться реализовать парочку "ручек" для понимания того, как это происходит с помощью EditorSwagger. Тем более, что он подсвечивает все ошибки и валидирует ваши контракты, пусть и не всегда очевидным образом.

Приходилось ли вам описать контракты и использовать их на своих проектах?