OpenAPI从Spring Boot生成Dart代码无空安全及默认值问题咨询

核心问题根源 #

Lombok的@NonNull是编译时工具注解，仅用于生成Java代码内部的非空校验逻辑，并不会被OpenAPI生成器识别为字段非空的标记。OpenAPI生成器依赖的是符合OpenAPI规范的元数据（比如Schema定义）或JSR-380校验注解，而非Lombok的私有注解。

为什么设置默认值能生效？ #

当你给Java属性添加默认值时，OpenAPI生成器会推断该字段存在默认值，因此在生成的OpenAPI Schema中会标记为nullable: false（因为即使接口返回/请求中没有该字段，也会有默认值兜底），最终生成的Dart代码就会对应非空类型。但这种方式属于“间接生效”，并非规范做法，还可能引入不符合业务逻辑的默认值。

正确的解决方法 #

要让生成的Dart代码严格遵循空安全，需要用OpenAPI生成器能识别的方式标记非空字段：

1. 使用标准校验注解
   用jakarta.validation.constraints.NotNull（Spring Boot 3+）或javax.validation.constraints.NotNull（Spring Boot 2.x）标记非空字段，OpenAPI生成器会自动将这类字段的Schema设置为nullable: false。

2. 显式指定Schema属性
   直接通过io.swagger.v3.oas.annotations.media.Schema注解的nullable属性明确标记：

   @Schema(nullable = false)
   private String username;
   

3. 确保生成器启用空安全
   在OpenAPI生成器的配置中开启Dart空安全支持，比如：

   • 使用CLI生成时添加参数：--dart.null-safety=true
   • Maven插件配置中添加：

     <configuration>
       <generatorName>dart</generatorName>
       <configOptions>
         <null-safety>true</null-safety>
       </configOptions>
     </configuration>
     

代码示例 #

修改后的Java实体类

import lombok.Data;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotNull;

@Data
public class User {
    @NotNull
    @Schema(nullable = false)
    private String username;
    
    @Schema(nullable = true)
    private Integer age;
}

生成的Dart类（空安全生效）

class User {
    String username;
    int? age;

    User({
        required this.username,
        this.age,
    });

    // 省略序列化/反序列化方法
}

额外注意 #

• 确保使用的OpenAPI生成器版本在v5.0以上，该版本开始原生支持Dart空安全。
• 如果是通过SpringDoc自动生成OpenAPI文档，需确保SpringDoc能正确识别@NotNull和@Schema注解，生成符合要求的Schema定义。

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