如何为Swagger REST API文档生成Java客户端代码

Question

我的情景如下。

我有一个Swagger .json文件，例如：http://petstore.swagger.io/v2/swagger.json 我想要使用生成的Java客户端来访问上述REST API，例如：

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实现存储。

我已成功使用命令为宠物商店生成了服务器存根：

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项目代码是服务器端代码。 它具有像@RequestMapping和PetApi.java中的注释，还有一个WebMvcConfiguration.class。

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

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

谢谢回答！

- csikos.balint

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 Generator是Swagger Codegen项目的一部分（免费、开源），您也可以在本地运行Swagger generator）

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

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

- William Cheng

Answer 2

您的情况下，您的命令应该像这样。

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转换为Java的其他选项包括：

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

使用GitHub项目时，您可以自行决定在将Swagger转换为Java客户端或服务器代码时使用哪个库（例如Jersey、Jersey2、OkHttp-Gson等）。在generator.swagger.io上，您也可以决定使用哪个库。可能会有一个增强功能可用于选择要使用的库。需要考虑的是，swagger.io选项完全免费，而Restlet和APIMATIC则是免费增值服务。

- st.huber

---

editor.swagger.io 使用 generator.swagger.io 来生成 API 客户端、服务器存根和 API 文档。generator.swagger.io 也由 swagger codegen 项目支持。 - William Cheng

@wing328 你说得对，我知道使用swagger-codegen项目或在线版本(generator.swagger.io)仍然有所不同。在线上，你无法选择用于转换的库。 - st.huber

您可以参考 https://github.com/swagger-api/swagger-codegen#online-generators 了解如何传递各种选项以自定义输出。对于 editor.swagger.io，也有一个讨论添加菜单以自定义输出：https://github.com/swagger-api/swagger-editor/issues/713 - William Cheng

感谢您的建议，我已经相应更新了我的回答。如果现在对您来说没问题，请随意点赞。 - st.huber

仅供澄清，宠物店的最终URL为https://petstore.swagger.io:443/v2/swagger.json，否则swagger-codegen-cli.jar将抛出com.fasterxml.jackson.core.JsonParseException异常。 - devwebcl

Answer 3

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

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

希望这能对您有所帮助， Thierry

- Thierry Templier

---

谢谢你的回答。我不知道怎么会错过手册中的这一部分，但这正是我需要的答案。 - csikos.balint

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 <语言> -i <Swagger规范的路径或URL>

更多信息请参考这里

- zygimantus

Answer 5

这只是对@wing328答案的一种简单扩展。

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

在使用Swagger UI进行API测试时，可以通过将Swagger规范JSON负载发送到UI来代替传统的URL方式。这种方法可以确保UI以最准确的方式呈现API，并且可以让用户更轻松地理解API的结构和功能。要使用这种方法，请将Swagger规范JSON负载作为请求正文发送到UI，并确保请求头包含Content-Type: application/json。

Instead of using swaggerUrl with an URL to the OpenAPI/Swagger spec, you can also include the spec in the JSON payload with spec, e.g.

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

更多信息：官方文档

- so-random-dude

---

我觉得这与主题无关。我认为在UNIX系统上使用或安装'curl'命令是一个不同的问题。 - csikos.balint

@csikos.balint 这是相关的，因为当我尝试时，它导致了证书错误... 我没有在这里添加随机的curl选项。 - so-random-dude

Answer 6

尽管Swagger生成器可以生成Java SDK，但APIMATIC SDK已经非常成熟、详细，并且比Swagger Gen提供更多的灵活性。你应该尝试一下APIMATIC SDK生成器，你会喜欢它的。

- Waseem Hassan