SWAGGER: что представляет из себя спецификация для rest api?
Мне необходимо разработать rest api для одной системы.
Опыта разработки с использованием спецификаций - нет.
Хотел бы в этом разобраться при решении текущей задачи.
В качестве инструмента для описания спецификации буду использовать swagger.
Возникли следующие вопросы:
1. В каком порядке принято описывать спецификации и разрабатывать сам сервер/клиент для api ? Первым делом пишется спецификация, потом api ?
2. Как спецификация напрямую влияет на функционал сервера/клиента для api (кроме того, что описывает его) ?
Т.е. если в спецификации описано, что при добавлении данных необходим тип данных "число", а клиент отправляет "строку", то сервер обязан отдавать ошибку ?
Суть вопроса в том, что все должно 1в1 соответствовать спецификации ? Если да, то это как-то программно контролируется (с помощью тестов) ? - возможно какие-то инструменты есть для этого ?
3. У swagger есть инструменты для генерации клиента и сервера по описанной спецификации.
Как часто этим пользуются, и принято ли этим пользоваться ? Какие есть минусы и плюсы ? И какие подходы бывают ?
Просьба поделиться опытом, любая информация будет полезной.
1. Либо сначала разрабатывается спека, а потом пишется API. Это если у вас уже готовое подробное ТЗ есть.
Либо пишется API и параллельно (либо после) документируется. В идеале — первый вариант. Мне приходилось работать только по второму.
2. Это просто документация. Насколько строго вы будете валидировать данные - ваше дело. Тестирование — это тоже ваше дело, и другими программными средствами.
3. Насколько я знаю — нет. Да и не представляю, что вы имеете ввиду. Нажать кнопку и получить готовый продукт? На каком ЯП? На каком фреймворке? Как-то фантастично. Вряд ли. Берете какой-то фрейм и пилите сами.
Swagger — это вообще примитивнейший продукт для документирования API. Все что он делает — читает файл в формате OpenAPI и отображает его содержание в удобном для чтения формате. Ну еще запросы к API умеет выполнять для проверок. И всё.
3. Насколько я знаю — нет. Да и не представляю, что вы имеете ввиду. Нажать кнопку и получить готовый продукт? На каком ЯП? На каком фреймворке? Как-то фантастично. Вряд ли. Берете какой-то фрейм и пилите сами.
Swagger — это вообще примитивнейший продукт для документирования API. Все что он делает — читает файл в формате OpenAPI и отображает его содержание в удобном для чтения формате. Ну еще запросы к API умеет выполнять для проверок. И всё.
Не все так примитивно. Есть разный инструментарий вокруг спецификации.
Простой
Средний
Средний
Простой
Средний
