如何在Swagger中指定数组([])类型，生成数组而非List类型

问题现象 #

配置OpenAPI（Swagger）Schema的type: array后，自动生成的Java类中对应属性默认是List类型，未生成预期的原生数组。

现有YML配置片段 #

...
probabilities:
  type: "array"
  items:
    type: "number"
    format: "double"
    minimum: 0
    maximum: 1
  description: "Vector with probabilities"
  example: [ 0.5, 0.3, 0.1 ]
...

默认生成的代码 #

...
@JsonProperty("probabilities")
@SerializedName("probabilities")
private List<Double> probabilities = new ArrayList<Double>();
...

调整方案 #

Swagger/OpenAPI代码生成器默认把array类型映射为java.util.List，这是生成器的默认规则，和你写的Schema字段定义本身没关系，选下面任意一种方式调整就行：

• 全局生效：如果项目里所有数组字段都要生成原生数组，直接改代码生成插件的配置参数：
  • 官方swagger-codegen（包括Maven、Gradle插件）：加配置项useArrayForArrays=true，同时在类型映射里配好基础类型数组的映射规则，就不会生成包装类数组。
  • openapi-generator（目前主流维护的Swagger生成工具）：加配置项arrayAsArray=true就可以。
  • 第三方封装的Swagger插件（比如Knife4j、EasyCode带的Swagger生成模块）：在插件的类型映射配置页，找到array类型的默认映射，把原来的java.util.List换成对应原生数组类型就行。
• 单字段生效：如果只需要probabilities这一个字段生成为数组，不用改全局配置，直接在这个字段的Schema定义里加扩展声明：

probabilities:
  type: "array"
  items:
    type: "number"
    format: "double"
    minimum: 0
    maximum: 1
  # 给Java生成器指定该字段的实际类型
  x-java-type: double[]
  description: "Vector with probabilities"
  example: [ 0.5, 0.3, 0.1 ]

改完重新跑代码生成，目标属性就会生成预期的原生数组格式：

...
@JsonProperty("probabilities")
@SerializedName("probabilities")
private double[] probabilities;
...

如果最后生成的是包装类Double[]而不是基础类型double[]，检查生成器的基础类型映射配置，打开「优先使用基础类型」的开关即可。

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