SWAGGER: что представляет из себя спецификация для rest api?

Question

[topuserman]

Мне необходимо разработать rest api для одной системы.
Опыта разработки с использованием спецификаций - нет.
Хотел бы в этом разобраться при решении текущей задачи.
В качестве инструмента для описания спецификации буду использовать swagger.

Возникли следующие вопросы:

1. В каком порядке принято описывать спецификации и разрабатывать сам сервер/клиент для api ? Первым делом пишется спецификация, потом api ?

2. Как спецификация напрямую влияет на функционал сервера/клиента для api (кроме того, что описывает его) ?
Т.е. если в спецификации описано, что при добавлении данных необходим тип данных "число", а клиент отправляет "строку", то сервер обязан отдавать ошибку ?
Суть вопроса в том, что все должно 1в1 соответствовать спецификации ? Если да, то это как-то программно контролируется (с помощью тестов) ? - возможно какие-то инструменты есть для этого ?

3. У swagger есть инструменты для генерации клиента и сервера по описанной спецификации.
Как часто этим пользуются, и принято ли этим пользоваться ? Какие есть минусы и плюсы ? И какие подходы бывают ?

Просьба поделиться опытом, любая информация будет полезной.

Answer 1

[Сергей delphinpro]

1. Либо сначала разрабатывается спека, а потом пишется API. Это если у вас уже готовое подробное ТЗ есть.
Либо пишется API и параллельно (либо после) документируется. В идеале — первый вариант. Мне приходилось работать только по второму.
2. Это просто документация. Насколько строго вы будете валидировать данные - ваше дело. Тестирование — это тоже ваше дело, и другими программными средствами.
3. Насколько я знаю — нет. Да и не представляю, что вы имеете ввиду. Нажать кнопку и получить готовый продукт? На каком ЯП? На каком фреймворке? Как-то фантастично. Вряд ли. Берете какой-то фрейм и пилите сами.

Swagger — это вообще примитивнейший продукт для документирования API. Все что он делает — читает файл в формате OpenAPI и отображает его содержание в удобном для чтения формате. Ну еще запросы к API умеет выполнять для проверок. И всё.

Comments

[Ромзес Панагиотис]

3. Насколько я знаю — нет. Да и не представляю, что вы имеете ввиду. Нажать кнопку и получить готовый продукт? На каком ЯП? На каком фреймворке? Как-то фантастично. Вряд ли. Берете какой-то фрейм и пилите сами.

Отнюдь не фантастика. Зайдите на https://openapi-generator.tech/

Swagger — это вообще примитивнейший продукт для документирования API. Все что он делает — читает файл в формате OpenAPI и отображает его содержание в удобном для чтения формате. Ну еще запросы к API умеет выполнять для проверок. И всё.

Не все так примитивно. Есть разный инструментарий вокруг спецификации.

[Сергей delphinpro]

Ромзес Панагиотис, интересно