Генерируем в 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 будет выглядеть примерно как-то так:

<?xml version="1.0" encoding="UTF-8"?>     <project xmlns="http://maven.apache.org/POM/4.0.0"     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">     <modelVersion>4.0.0</modelVersion>     <groupId>org.mycompany</groupId>     <artifactId>xyz-api-service</artifactId>     <version>1.0-SNAPSHOT</version>     <properties>     <maven.compiler.source>17</maven.compiler.source>     <maven.compiler.target>17</maven.compiler.target>     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>     <spring-boot-starter-web.version>2.4.4</spring-boot-starter-web.version>     <spring-data-jpa.version>2.4.6</spring-data-jpa.version>     <jackson-databind-nullable.version>0.2.6</jackson-databind-nullable.version>         <springdoc-openapi-ui.version>1.8.0</springdoc-openapi-ui.version>     <openapi-generator-maven-plugin.version>7.1.0</openapi-generator-maven-plugin.version>     <maven-clean-plugin.version>2.4.1</maven-clean-plugin.version>     <swagger-yaml>xyz-swagger-v${swagger-yaml.version}.yaml</swagger-yaml>     <swagger-yaml.version>1.0.0</swagger-yaml.version>     </properties>     <dependencies> <dependency>     <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring-boot-starter-web.version}</version> </dependency> <dependency> <groupId>org.springframework.data</groupId>             <artifactId>spring-data-jpa</artifactId>             <version>${spring-data-jpa.version}</version>         </dependency>     <dependency>     <groupId>org.openapitools</groupId>     <artifactId>jackson-databind-nullable</artifactId>     <version>${jackson-databind-nullable.version}</version> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>${springdoc-openapi-ui.version}</version> </dependency> </dependencies>     <build>     <plugins>     <plugin>     <artifactId>maven-clean-plugin</artifactId>     <version>${maven-clean-plugin.version}</version>     <configuration>     <filesets>     <fileset>     <directory>${project.basedir}/src/main/java</directory> <includes> <include>**</include> </includes> <followSymlinks>false</followSymlinks> </fileset> </filesets> </configuration> </plugin> <plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>${openapi-generator-maven-plugin.version}</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <inputSpec>${project.basedir}/src/main/resources/${swagger-yaml}</inputSpec> <generatorName>spring</generatorName> <apiPackage>org.mycompany.xyz.api</apiPackage> <modelPackage>org.mycompany.xyz.model</modelPackage> <supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate <configOptions> <delegatePattern>true</delegatePattern> </configOptions> <output>${project.basedir}</output> </configuration> </execution> </executions> </plugin>     </plugins>     </build> </project> 

При обновлении версии файла будет достаточно заменить свойство swagger-yaml.version. А формат имени файла указывается в свойстве swagger-yaml.

Чтобы сгенерировать файлы, просто выполните из консоли или интерфейса вашей IDE две команды жизненного цикла Maven: clean и compile.

И сгенерированные файлы появятся прямо в рабочей директории. При новой генерации старые файлы будут удаляться автоматически

Важно: не пытайтесь запускать указанные плагины напрямую. Напрямую они просто не будут работать.

Небольшой штришок — чтобы не мусорить в репозитории, нужно добавить в .gitignore (для Git, в Mercurial этот файл называется .hgignore) пометку о том, что нужно игнорировать временные файлы, которые создаёт плагин:

.openapi-generator