如何在 swagger-spring-mvc 中为 swagger-codegen 表示具有泛型类型的字段，例如 List<Something>

Question

我正在使用 swagger-spring-mvc 0.9.5 并且在我的响应数据中有这样的字段：

@ApiModelProperty("Some description")
private List<Account> accounts;

问题的简短版本：我怎样才能从这个带注释的 Java 到例如通过 swagger-codegen 实现目标 C？

由此生成的大摇大摆的 JSON 是：

accounts: {
  description: "Some description",
  items: {
    type: "Account"
  },
  required: false,
  type: "List"
}

我的同事正在将它输入 swagger-codegen 以生成 Objective C 类，它正在生成无法编译的代码。

@property (nonatomic, strong) NSArray<Optional, NSArray> *accounts;

因为NSArray（在< > 内）不是协议。

swagger 模板文件（mustache）为每个模型创建一个协议。当在数组上指定该协议时，JSONModel 会拾取它以从列表/数组中的数据生成正确的模型。所以在这种情况下，预期的输出是

@property (nonatomic, strong) NSArray<Optional, MAAccount> *accounts;

这将创建一个MAAccount 的NSArray（Account 是对象类型，MA 是 swagger 已经拥有的前缀）。

如果我们手动编辑 swagger JSON 以将 List 更改为 array（如在各种类似情况下所建议的那样），输出是正确的，但我们希望避免这个手动步骤。

所以我尝试让 swagger-spring-mvc 使用 "array":

@ApiModelProperty(value = "Some description", dataType = "array")
private List<Account> accounts;

但后来发现 dataType 在 swagger-spring-mvc 0.9.5 中被忽略了，从外观上看，在 springfox 2.0 中它被忽略，除非它是完全限定的 Java 类名。

有没有办法通过让 swagger-spring-mvc/springfox 使用 "array" 或任何其他方式来实现这一点？

Answer 1

在大多数情况下，swagger 注释只是帮助 springfox 引擎推断有关类型的附加信息，例如描述/隐藏/只读等，这些信息在类型系统中是不可用的。它也可以用作拐杖来表示不易推断的类型。数据类型可以被覆盖，但只是为了类型安全，正如评论中指出的那样。

具体来说，我读到 dataType 将被忽略，除非它是完全限定的类名。

就像@CupawnTae 建议的那样，version 2.x of springfox 支持使用代码生成友好且与语言无关的泛型类型表示来呈现泛型类型的选项。

在创建/配置您的文档时，您需要使用 forCodeGeneration 选项指定呈现的 swagger 服务描述需要对代码生成友好

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
      ...
      .forCodeGeneration(true)
      ...;
}

这将导致 springfox 呈现像List<String> 这样的泛型类型

• 当forCodeGeneration 设置为true 时ListOfString
• 当forCodeGeneration 设置为false 时List«String»