如何在 swagger-spring-mvc for swagger-codegen 中用 List<Something> 等泛型类型表示字段

Question

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

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

问题的简短版本：我怎样才能从这个带注释的 Java 得到例如Objective C 通过 swagger-codegen?

由此产生的招摇 JSON 是：

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

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

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

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

swagger 模板文件（小胡子）为每个模型创建一个协议。当在数组上指定该协议时，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 class 名称。

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

Answer 1

在大多数情况下，swagger 注释只是帮助 springfox 引擎推断有关类型的其他信息，例如 description/hidden/readonly 等，这些信息无法从类型系统中获得。它还可以用作表示不容易推断的类型的拐杖。数据类型可以被覆盖，但正如评论中指出的那样只是为了类型安全。

Specifically, I read that dataType will be ignored unless it's a fully-qualified class name.

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

当 creating/configuring 您的摘要时，您需要使用 forCodeGeneration 选项

指定呈现的 swagger 服务描述需要代码生成友好

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

这将导致 springfox 渲染像 List<String>

这样的泛型类型

forCodeGeneration

How to represent fields with generic types like List<Something> in swagger-spring-mvc for swagger-codegen