使用 OpenAPI 生成带有 Lombok 注解的 Model-工具盒子

1、概览 {#1概览}

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

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

2、项目设置 {#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 {#3使用-openapi-生成-model}

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

3.1、创建 model 规范 {#31创建-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 {#32生成带有-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、生成的代码 {#33生成的代码}

让我们来看看生成的 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 会生成一个全参构造函数，该构造函数接收类中所有字段的参数。