使用swagger-gradle-plugin(OAS3)注解生成MultivaluedMap参数定义

背景（OAS2生成的参数定义） #

此前使用OAS2版本插件时，生成的参数JSON定义如下：

{
  "description": "parameters",
  "in": "body",
  "name": "body",
  "required": false,
  "schema": {
    "type": "object",
    "additionalProperties": {
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  }
}

遇到的问题 #

切换至OAS3后，以下两种注解写法均无法生成符合要求的参数：

1. 基础注解写法：

@Parameter(description = "parameters") @NotNull MultivaluedMap<String, String> parameters

2. 尝试additionalProperties workaround但无效：

@Parameter(description = "paremeters", content = @Content(schema = @Schema(type = "object"),
additionalPropertiesSchema = @Schema(type = "string")))
@NotNull MultivaluedMap<String, String> parameters

解决方案 #

需要在@Schema中明确配置additionalProperties为字符串数组类型，对应OAS2里的结构。正确的注解写法如下：

@Parameter(
    description = "parameters",
    content = @Content(
        schema = @Schema(
            type = "object",
            additionalProperties = @Schema(
                type = "array",
                items = @Schema(type = "string")
            )
        )
    )
)
@NotNull
MultivaluedMap<String, String> parameters

说明 #

原OAS2定义中，additionalProperties对应的是元素为字符串的数组（array[string]），而之前的错误写法把它设成了单个字符串（string）。通过将additionalProperties的@Schema指定为type = "array"，并配置items为字符串类型，就能生成和OAS2一致的参数结构，在Swagger UI中呈现出预期效果。

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