使用 OpenAPI 生成带有 Lombok 注解的 Model

教程

1、概览

Lombok 是一个 Java 库，有助于减少 getter、setter 等模板代码。OpenAPI 提供了一个属性，用于自动生成带有 Lombok 注解的 Model。

在本教程中，我们将探讨如何使用 OpenAPI 代码生成器生成带有 Lombok 注解的 Model。

2、项目设置

首先，让我们创建一个 Spring Boot 项目，并添加 Spring Boot Starter Web 和 Lombok 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.1.2</version>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.28</version>
    <scope>provided</scope>
</dependency>

此外，我们还需要 Swagger 注解、Gson 和 Java Annotation API 依赖，以防止在生成的代码中出现与包相关的错误：

<dependency>
    <groupId>javax.annotation</groupId>
    <artifactId>javax.annotation-api</artifactId>
    <version>1.3.2</version>
</dependency>

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.6.2</version>
</dependency>

在下一节中，我们将为一个名为 Book 的 model 创建一个 API 规范，然后使用 OpenAPI 代码生成器生成带有 Lombok 注解的代码。

3、使用 OpenAPI 生成 Model

OpenAPI 的理念是在开始实际编码之前编写 API 规范。在这里，我们将创建一个规范文件，并根据规范生成一个 model。

3.1、创建 model 规范

首先，让我们在 resources 文件夹中创建一个名为 bookapi.yml 的新文件，以定义 Book 规范：

openapi: 3.0.2
info:
  version: 1.0.0
  title: Book Store
  license:
    name: MIT
paths:
    /books:
      get:
        tags:
          - book
        summary: Get All Books
        responses:
          200:
            description: successful operation
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Book'
          404:
            description: Book not found
            content: { }
components:
  schemas:
    Book:
      type: object
      required:
        - id
        - name
        - author
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        author:
          type: string

在上述规范中，我们定义了包含 id、name 和 author 字段的 Book schema。此外，我们还定义了一个端点，用于获取所有已存储的 book。

3.2、生成带有 Lombok 注解的 Model

定义完 API 规范后，让我们在 pom.xml 中添加 OpenAPI plugin ，以帮助根据规范生成代码：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>4.2.3</version>
    <executions>
        <execution>
        <goals>
            <goal>generate</goal>
        </goals>
        <configuration>
            <inputSpec>${project.basedir}/src/main/resources/bookapi.yml</inputSpec>
        <generatorName>java</generatorName>
        <configOptions>
            <additionalModelTypeAnnotations>@lombok.Data @lombok.NoArgsConstructor @lombok.AllArgsConstructor</additionalModelTypeAnnotations>
        </configOptions>
        <generateApis>false</generateApis>
        <generateSupportingFiles>false</generateSupportingFiles>
        <generateApiDocumentation>false</generateApiDocumentation>
        </configuration>
    </execution>
    </executions>
</plugin>

在这里，我们指定了规范文件的位置，以便插件在生成过程中进行检查。此外，我们还添加了 additionalModelTypeAnnotations 属性，以便为 model 添加三个 Lombok 注解。

为简单起见，我们禁用辅助文件和 API 文档的生成。

最后，执行 Maven install 命令生成 model：

$ ./mvnw install

上述命令将在 target 文件夹中生成 Book model。

3.3、生成的代码

让我们来看看生成的 Book model：

@lombok.Data @lombok.NoArgsConstructor @lombok.AllArgsConstructor
@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen", date = "2023-08-16T09:16:34.322697262Z[GMT]")
public class Book {
    public static final String SERIALIZED_NAME_ID = "id";
    @SerializedName(SERIALIZED_NAME_ID)
    private Long id;
  
    public static final String SERIALIZED_NAME_NAME = "name";
    @SerializedName(SERIALIZED_NAME_NAME)
    private String name;
  
    public static final String SERIALIZED_NAME_AUTHOR = "author";
    @SerializedName(SERIALIZED_NAME_AUTHOR)
    private String author;
    // ... 
}

在上面生成的代码中，我们在插件中使用 additionalModelTypeAnnotations 属性定义的三个 Lombok 注解被添加到了 model 类中。

@Data 注解有助于在编译时生成 getter、setter 等方法。@NoArgsConstructor 会生成一个无参构造函数，而 @AllArgsConstructor 会生成一个全参构造函数，该构造函数接收类中所有字段的参数。

4、总结

在本文中，我们学习了如何使用 OpenAPI 代码生成器生成带有 Lombok 注解的 model。通过添加 additionalModelTypeAnnotations 属性，我们可以灵活地添加所需的 Lombok 注解。

参考：https://www.baeldung.com/java-openapi-lombok-create-models