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

Question

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

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

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

由此生成的 swagger JSON 是:

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

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

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

因为NSArray (在 < > 内)不是协议(protocol)。

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

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

这将创建一个 NSArray的 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"还是通过其他方式？

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支持使用代码生成友好和语言不可知的通用类型表示来呈现通用类型的选项。

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

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

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

• 作为ListOfString什么时候forCodeGeneration设置为真
• 作为List«String»什么时候forCodeGeneration设置为假