如何为 swagger REST API 文档生成 java 客户端代码

Question

我的场景如下。

我有一个招摇的 .json 例如：http://petstore.swagger.io/v2/swagger.json 我想为上面的 REST API 使用生成的 java 客户端，例如：

PetApi petApi = new PetApi();
Pet pet = new Pet;
pet.setName("cica");
pet.setId(1L);
petApi.addPet(pet);
System.out.println(petApi.getById(1L));`

扩展输出：cica，新宠物按照 REST API 实现存储。

我已使用以下命令成功为 petstore 生成了服务器存根：

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate
     -i http://petstore.swagger.io/v2/swagger.json
     -l spring-mvc
     -o samples/server/petstore/spring-mvc

但是这个 maven 项目代码是一个服务器代码。它在PetApi.java 中有@RequestMapping 之类的注解，还有WebMvcConfiguration.class。

我不想拥有服务器存根。我想要一个用于 petstore REST API 的客户端库。

有没有工具可以为我生成合适的客户端库？我应该修改服务器存根，因此它具有所有模型还是应该使用简单的 springRestTemplate？

感谢您的回答！

Answer 1

除了使用 JAR，您还可以使用 https://generator.swagger.io 在线生成 SDK（Java、Ruby、PHP 等），而无需安装任何东西。这是一个例子：

curl -X POST -H "content-type:application/json" -d '{"swaggerUrl":"http://petstore.swagger.io/v2/swagger.json"}' https://generator.swagger.io/api/gen/clients/java

这是一个示例响应：

{"code":"1445940806041","link":"https://generator.swagger.io/api/gen/download/1445940806041"}  

然后您可以从该链接下载压缩的 SDK。

更多自定义https://generator.swagger.io输出的选项，请参考https://github.com/swagger-api/swagger-codegen#online-generators

（Swagger 生成器是 Swagger Codegen 项目（免费、开源）的一部分，您也可以运行本地 Swagger 生成器）

截至 2017 年 7 月，Java API 客户端生成器支持以下 HTTP 库：Jersey 1.x & 2.x、Retrofit 1.x & 2.x、okhttp、Feign、RESTEasy、RestTemplate

更新：2018 年 5 月，Swagger Codegen 的大约 50 位顶级贡献者和模板创建者决定分叉 Swagger Codegen 以维护一个名为 OpenAPI Generator 的社区驱动版本。更多信息请参考Q&A。

Answer 2

我认为您没有为 Swagger Codegen 的参数-l 使用正确的值（您使用的是服务器端技术spring-mvc）。您可以尝试使用值java。

您还可能注意到有一个工具，Restlet Studio，它允许从 Swagger 内容生成代码。对于 Java，它主要依赖于 Restlet 框架，但我认为它可以满足您的需求。

希望对你有帮助 蒂埃里

Answer 3

对于您的场景，您的命令应如下所示

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate
 -i http://petstore.swagger.io/v2/swagger.json
 -l java
 -o samples/server/petstore/spring-mvc

将 swagger 转换为 jave 的其他选项是：

• swagger-codegen
• generator.swagger.io
• editor.swagger.io
• Restlet
• APIMATIC

尽管使用 GitHub 项目，在将 swagger 转换为 Java 客户端或服务器代码时，由您决定使用哪个库（jersey、jersey2、okhttp-gson 等）。使用 generator.swagger.io 你也可以decide which library to use。可能有一个enhancement to editor.swagger.io 也可以选择要使用的库。需要考虑的是 swagger.io 选项是完全免费的，而 Restlet 和 APIMATIC 是免费增值的。

Answer 4

可能是最快和最简单的方法：

1. wget https://oss.sonatype.org/content/repositories/releases/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar
2. java -jar swagger-codegen-cli-2.2.1.jar generate -l <language> -i <pathOrUrlOfSwaggerSpec>

更多信息here

Answer 5

只是对@wing328's answer 的一个愚蠢的扩展。

curl -X POST -H "content-type:application/json" -d '{"swaggerUrl":"http://petstore.swagger.io/v2/swagger.json"}' https://generator.swagger.io/api/gen/clients/java

如果导致这个错误（SSL证书问题）

curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.haxx.se/docs/sslcerts.html

为 curl 添加一个 -k 开关。示例：

curl -k -X POST -H "content-type:application/json" -d '{"swaggerUrl":"http://petstore.swagger.io/v2/swagger.json"}' https://generator.swagger.io/api/gen/clients/java

响应

{"code":"7e542952-5385-4e34-8cf6-6196722fb18b","link":"https://generator.swagger.io/api/gen/download/7e542952-5385-4e34-8cf6-6196722fb18b"}

发送完整的 swagger 规范 JSON 有效负载而不是 URL

而不是使用带有指向 OpenAPI/Swagger 规范的 URL 的 swaggerUrl， 您还可以使用规范在 JSON 有效负载中包含规范，例如

{
  "options": {},
  "spec": {
    "swagger": "2.0",
    "info": {
      "version": "1.0.0",
      "title": "Test API"
    },
    ...
  }
}

更多信息：Official Doc

Answer 6

虽然 swagger 生成器生成 Java SDK，但 APIMATIC sdk 相当成熟、详细，并且比 Swagger Gen 提供了更多的灵活性。您应该尝试 APIMATIC sdk 生成器，您会喜欢的。