Я пытаюсь включить swagger-codegen в мой новый проект с нуля, используя Java (jaxrs-jersey2).
Существует множество ресурсов, которые уже документируют различные части проекта; однако я до сих пор не смог найти ни одного высокоуровневого совета о том, как лучше всего использовать эти инструменты.
Насколько я понимаю, swagger-codegen сможет генерировать код на стороне клиента для взаимодействия с моим API, так что мне не придется писать это самому. Это произойдет, посмотрев на файл swagger.yaml (2.0) или openapi.yaml (3.0). Эта часть понятна.
Однако существует несколько способов создания этого файла спецификации. Насколько я понимаю, есть два основных способа:
Напишите реализацию сервера, используя комбинацию аннотаций jaxrs и Swagger - используйте плагин maven как часть шага компиляции, генерируя файл спецификации swagger.yaml, который будет использоваться плагином поколения клиента.
Сначала напишите спецификацию swagger.yaml и сгенерируйте код заглушки сервера для Джерси, реализуя только бизнес-логику, отдельно от всех шаблонов серверов.
Какой из этих двух способов является рекомендуемым рабочим процессом? Похоже, что (2) означает написание меньшего количества кода и сосредоточение внимания только на логике приложения, не слишком заботясь о клее, специфичном для Джерси, чтобы заставить API работать. Это также означает, что единственным источником правды для API становится простой файл yaml, а не куча кода Джерси.
Однако я не уверен, как правильно настроить это:
- Должна ли моя сборка иметь фазу компиляции, на которой заглушки сервера постоянно обновляются?
- Должен ли я просто расширять сгенерированную заглушку сервера и никогда не беспокоиться о том, чтобы аннотировать пути API с помощью @Path, @GET и т. Д.?
- Не понимаю ли я сценарий использования для создания заглушек сервера? То есть Первый подход (сначала код Джерси) более уместен?
- Если между двумя подходами нет реальной разницы, когда вы выберете (1) вместо (2) и наоборот?
Большое спасибо.