Генерируем в maven Java-модуль для OpenAPI из Swagger YAML
Допустим отдел аналитики подготовил нам Swagger YAML с описанием API доступа к какому-то сервису: xyz-swagger-v1.0.0.yaml.
Как автоматизировать генерацию библиотеки для доступа к API по этому описанию, если у вас maven? Полного мануала почему-то нигде нет, так что я собрал в одну всю информацию о реализации и возможных проблемах.
Для генерации нам понадобятся следующие плагины для maven:
maven-clean-plugin — удаляет файлы. Он нужен, чтобы очистить директорию с исходниками проекта от предыдущей сгенерированной версии. Настройки, на которые следует обратить внимание:
configuration.filesets.fileset.directory: ${project.basedir}/src/main/java — мы будем очищать директорию самого приложения
configuration.filesets.fileset.includes.include: ** — не только очищать директорию /src/main/java, но и удалять её саму.
openapi-generator-maven-plugin — генерирует по OpenAPI YAML для Swagger Java-классы. Настройки, на которые следует обратить внимание:
apiPackage — пространства имён для классов сервисов API
modelPackage — пространства имён для классов моделей
output: ${project.basedir} — если настроить его так, сгенерированные файлы падали не в target, а прямо в папку с кодом
Сгенерированные файлы используют аннотации и методы из внешних библиотек. Поэтому в dependencies нужно будет добавить:
spring-boot-starter-web версии 2.4.4
spring-data-jpa версии версии 2.4.6
jackson-databind-nullable версии 0.2.6
springdoc-openapi-ui версии 1.8.0
Если какой-то из этих версий нет в доступных вашему проекту репозиториях — используйте те, которые доступны. Но увеличивайте версию осторожно и перепроверяйте после каждого изменения: как минимум spring-boot-starter-web и spring-data-jpa не совсем обратно совместимы и при повышении их версии в сгенерированных файлах может перестать распозновать зависимости.
Создайте пустой проект с поддержкой Maven и удалите весь код из папки java.
Поместите в папку /src/main/resources/ файл с YAML-описанием OpenAPI для Swagger. В моём примере это xyz-swagger-v1.0.0.yaml
В результате pom.xml будет выглядеть примерно как-то так:
4.0.0
org.mycompany
xyz-api-service
1.0-SNAPSHOT
17
17
UTF-8
2.4.4
2.4.6
0.2.6
1.8.0
7.1.0
2.4.1
xyz-swagger-v${swagger-yaml.version}.yaml
1.0.0
org.springframework.boot
spring-boot-starter-web
${spring-boot-starter-web.version}
org.springframework.data
spring-data-jpa
${spring-data-jpa.version}
org.openapitools
jackson-databind-nullable
${jackson-databind-nullable.version}
org.springdoc
springdoc-openapi-ui
${springdoc-openapi-ui.version}
maven-clean-plugin
${maven-clean-plugin.version}
${project.basedir}/src/main/java
**
false
org.openapitools
openapi-generator-maven-plugin
${openapi-generator-maven-plugin.version}
generate
${project.basedir}/src/main/resources/${swagger-yaml}
spring
org.mycompany.xyz.api
org.mycompany.xyz.model
ApiUtil.java
true
При обновлении версии файла будет достаточно заменить свойство swagger-yaml.version. А формат имени файла указывается в свойстве swagger-yaml.
Чтобы сгенерировать файлы, просто выполните из консоли или интерфейса вашей IDE две команды жизненного цикла Maven: clean и compile.
И сгенерированные файлы появятся прямо в рабочей директории. При новой генерации старые файлы будут удаляться автоматически
Важно: не пытайтесь запускать указанные плагины напрямую. Напрямую они просто не будут работать.
Небольшой штришок — чтобы не мусорить в репозитории, нужно добавить в .gitignore (для Git, в Mercurial этот файл называется .hgignore) пометку о том, что нужно игнорировать временные файлы, которые создаёт плагин:
.openapi-generator
