swagger или api first

Question

Я прочитал определения swagger и формат и понял, что определение swagger используется для описания API.

Было бы лучше написать определение swagger, а затем API? или написать API сначала, а затем чванство? У меня нет опыта в этом, и я бы хотел написать REST API и файл для чартов для приложения.

Answer 1

Я не думаю, что порядок действительно имеет значение. Оба метода получили легитимность в Swagger Getting Started Guide. Главное, что нужно генерировать от другого, поэтому вам не нужно вручную поддерживать оба.

В комментариях cricket_007 уже упоминал, что существуют инструменты для создания скелета веб-сервиса из определения swagger. Используя эти инструменты, было бы целесообразно сначала написать определение swagger. Это подход Top Down из руководства по началу работы.

Из руководства по началу работы Swagger, приведенного выше, вы можете видеть, что есть также инструменты, доступные для создания документов Swagger из java-кода, при условии, что вы используете определенную инфраструктуру, такую ​​как JAX-RS. Это подход Bottom Up.

Это сводится к личным предпочтениям. Если вы такой человек, который скорее не «соединил» вашу базу кода с Swagger и не зависеть от того, что ваше приложение не будет зависеть от Swagger, чтобы работать, то лучше всего подходит подход «снизу вверх». Однако, если вы хотите полностью охватить цепочку инструментов Swagger и действительно «купить» в ней, то подход сверху вниз, вероятно, лучший.

Также, если это для образовательных целей, подумайте о том, что вы хотите узнать. Если вы хотите узнать о написании API JSON REST с нуля (или используя что-то вроде JAX-RS), то подход «снизу вверх» научит вас больше. Однако, если ваша цель - узнать как можно больше о Swagger, то подход сверху вниз будет лучше.