如何配置Maven Swagger Codegen插件生成带@NotNull注解的DTO

问题描述 #

我使用Maven Swagger Codegen插件（v3.0.17），希望从OpenAPI Schema生成DTO时，给必填属性自动添加@NotNull或@NotEmpty注解。

我的OpenAPI Schema定义（inputSpec.yml）：

...
components:
    ...
  schemas:
    ...
    MyObjectDTO:
      type: object
      properties:
        id:
          type: integer
          format: int32
          readOnly: true
        groupId:
          type: integer
          format: int64
          required: true 
    ...
      required:
        - groupId
      description: my object 

但生成的DTO中groupId字段未包含校验注解：

@Schema(description = "my object")
@Validated
@javax.annotation.Generated(value = "com.myco.codegen.SpringCodegen", date = "2022-07-22T15:18:11.693263100-05:00[America/Chicago]")
public class MyObjectDTO   {

    ...
  @JsonProperty("groupId")
  private Integer groupId = null;
}

当该DTO传入带@Validated注解的Spring REST控制器时，若groupId未赋值，无法触发验证失败并返回400（Bad Request）错误。当前Maven插件配置如下：

<configuration>
    <language>com.myco.myproject.mypackage.swagger.codegen.OAS3SpringCodegen</language>
    <apiPackage>com.myco.myproject.mypackage.api</apiPackage>
    <modelPackage>com.myco.mypackage.api.model</modelPackage>
    <languageSpecificPrimitives>true</languageSpecificPrimitives>                   
    <generateApis>true</generateApis>
    <generateApiTests>false</generateApiTests>
    <generateModelTests>false</generateModelTests>
    <generateApiDocumentation>true</generateApiDocumentation>
    <generateModels>true</generateModels>
    <generateSupportingFiles>false</generateSupportingFiles>
    <importMappings>
        <importMapping>LocalDateTime=OffsetDateTime</importMapping>
    </importMappings>
    <configOptions>
        <throwsException>true</throwsException>                     
        <interfaceOnly>true</interfaceOnly>
        <java8>false</java8>
        <dateLibrary>java8</dateLibrary>
        <sourceFolder>.</sourceFolder>
        <useTags>true</useTags>
    </configOptions>
</configuration>

解决步骤 #

1. 启用Bean Validation配置 #

在Maven插件的<configOptions>中添加<useBeanValidation>true</useBeanValidation>，这是触发校验注解生成的关键配置：

<configOptions>
    <throwsException>true</throwsException>                     
    <interfaceOnly>true</interfaceOnly>
    <java8>false</java8>
    <dateLibrary>java8</dateLibrary>
    <sourceFolder>.</sourceFolder>
    <useTags>true</useTags>
    <!-- 开启Bean Validation注解生成 -->
    <useBeanValidation>true</useBeanValidation>
</configOptions>

2. 检查自定义Codegen类 #

由于使用了自定义的OAS3SpringCodegen类，需确保它未破坏默认注解生成逻辑：

• 若该类继承自SpringCodegen，检查是否重写了addBeanValidationAnnotations方法。如果有，需保证方法逻辑正确，为必填字段添加对应注解（非字符串类型用@NotNull，字符串类型用@NotEmpty）。
• 若未重写该方法，默认逻辑会自动处理必填字段的注解生成。

3. 确保项目依赖完整 #

生成的DTO会用到JSR-380校验注解，需在项目中引入Spring Validation依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

4. 验证生成结果 #

重新执行Maven生成命令后，groupId字段会自动带上@NotNull注解：

@Schema(description = "my object")
@Validated
@javax.annotation.Generated(value = "com.myco.codegen.SpringCodegen", date = "2022-07-22T15:18:11.693263100-05:00[America/Chicago]")
public class MyObjectDTO   {

    ...
  @JsonProperty("groupId")
  @NotNull
  private Integer groupId = null;
}

此时，当DTO传入带@Validated的Spring控制器时，未赋值groupId会触发校验失败，返回400 Bad Request错误。

内容的提问来源于stack exchange，提问作者Dave