java - 如何用 List 等泛型类型表示字段在 swagger-spring-mvc 中用于 swagger-codegen

Question

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

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

问题的简短版本：如何通过 swagger-codegen 从这个带注释的 Java 到例如 Objective 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;

这将创建一个NSArrayof MAAccount（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"或任何其他方式来实现这一点？

score 3 · Accepted Answer

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

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

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

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

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

这将导致 springfox 呈现泛型类型，例如List<String>

1 回答 1