关于Swagger中JsonNullable接口文档缺失信息的技术问询

项目中使用JsonNullable区分请求传入null（反序列化为JsonNullable.of(null)）和未传该字段（反序列化为JsonNullable.undefined()）的场景，依赖版本如下：

<swagger-parser.version>2.1.13</swagger-parser.version>
<jackson-databind-nullable.version>0.2.6</jackson-databind-nullable.version>
<openapi-generator-maven-plugin.version>7.0.0</openapi-generator-maven-plugin.version>

但自动生成的/v3/api-docs文档中，JsonNullable相关结构缺失value字段，仅保留present布尔标识：

"JsonNullableString": {
  "type": "object",
  "properties": {
    "present": {"type": "boolean"}
  },
  "description": "Some description",
  "example": 252534342
}

后端逻辑正常，但前端因文档信息不全，无法生成正确的请求代码。OpenAPI 3.0.3的原始定义仅使用nullable: true标记字段：

openapi: 3.0.3

info:
  title: Organization API
  description: Organization operations
  version: '1.0.0'

components:
  schemas:
    OrganizationUpdateData:
      type: object
      description: Organization update data
      properties:
        inn:
          type: string
          nullable: true
          description: inn
          example: 2395318535
          pattern: "^(\\d{10}|\\d{12})$"

1. 配置OpenAPI Generator识别JsonNullable #

在openapi-generator-maven-plugin的配置中添加jacksonNullable参数，开启对JsonNullable的原生支持：

<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>
        <!-- 其他已有配置 -->
        <configOptions>
          <jacksonNullable>true</jacksonNullable>
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>

该配置会让生成器自动解析JsonNullable的完整结构，在API文档中生成包含present和value的Schema。

2. 手动补充JsonNullable的完整Schema #

如果配置参数不生效，可在OpenAPI定义中手动声明JsonNullableString的完整结构，覆盖自动生成的内容：

components:
  schemas:
    JsonNullableString:
      type: object
      description: 可空字符串，支持区分"传入null"和"未传字段"
      properties:
        present:
          type: boolean
          description: 标识字段是否被传入（无论value是否为null）
        value:
          type: string
          nullable: true
          description: 字段的实际值，可为null
      example:
        present: true
        value: "2395318535"
    OrganizationUpdateData:
      type: object
      description: Organization update data
      properties:
        inn:
          $ref: "#/components/schemas/JsonNullableString"
          description: inn
          example:
            present: true
            value: "2395318535"
        # 其他字段...

前端可基于该完整Schema生成正确的请求体，明确区分{"present": true, "value": null}（传入null）和不包含该属性（未传字段）的场景。

3. 调整依赖版本兼容性 #

当前版本组合可能存在适配问题，尝试同步升级：

• 将jackson-databind-nullable升级至稳定版（如0.2.7）
• 将swagger-parser升级至与openapi-generator 7.0.0匹配的版本（推荐2.1.16+）
  版本匹配后，自动生成的Schema更大概率包含完整的JsonNullable字段。

修改配置或定义后重新生成API文档，检查JsonNullableString结构是否同时包含present和value字段，前端即可基于完整文档生成符合要求的请求代码。

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