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

How to generate java client code for swagger REST API documentation

提问by csikos.balint

My scenario is the following.

我的情况如下。

I have a swagger .json eg.: http://petstore.swagger.io/v2/swagger.jsonI want to use a generated java client for the REST API above, like:

我有一个 swagger .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));`

Expexted output: cicaand the new pet is stored according to the REST API implmentation.

Expexted 输出：cica根据 REST API 实现存储新宠物。

I have successfully generated server stub for the petstore with the command:

我已经使用以下命令成功地为 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

But this maven project code is a server code. It has annotations like @RequestMappingin PetApi.javaand also has a WebMvcConfiguration.class.

但是这个maven项目代码是服务器代码。它有像@RequestMappingin这样的注释PetApi.java，也有一个WebMvcConfiguration.class.

I do not want to have a server-stub. I want to have a client-library for the petstore REST API.

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

Is there a tool which can generate the appropriate client library for me? Should I modify the server-stub, hence it has all the models or should I use a simple springRestTemplate?

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

Thanks for the answers!

感谢您的回答！

采纳答案by Thierry Templier

I think that you don't use the right value for the parameter -lof Swagger Codegen (you use spring-mvcwhich is a server-side technology). You could try to use the value java.

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

You could also notice that there is a tool, the Restlet Studio, that allows to generate code from Swagger content. For Java, it mainly relies on the Restlet framework but I think that it could suit your needs.

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

Hope it helps you, Thierry

希望对你有帮助，蒂埃里

回答by William Cheng

Instead of using the JAR, you can also use https://generator.swagger.ioto generate the SDKs (Java, Ruby, PHP, etc) online without installing anything. Here is an example:

除了使用 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

and here is a sample response:

这是一个示例响应：

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

You can then download the zipped SDK from the link.

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

For more options on customizing the output of https://generator.swagger.io, please refer to https://github.com/swagger-api/swagger-codegen#online-generators

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

(Swagger Generator is part of the Swagger Codegen project (free, open source) that you can run your local Swagger generator as well)

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

As of July 2017, the Java API client generator supports the following HTTP libraries: Jersey 1.x & 2.x, Retrofit 1.x & 2.x, okhttp, Feign, RESTEasy, RestTemplate

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

回答by Huber

For your scenario your command should look like this

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

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

Other options to convert swagger to jave are:

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

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

• 招摇代码生成
• 生成器.swagger.io
• editor.swagger.io
• 休息区
• APIMATIC

Though with the GitHub project it's up to you to decide which library (jersey, jersey2, okhttp-gson, etc.) to use when converting swagger to Java client or server code. With generator.swagger.io you can also decide which library to use. There might be an enhancement to editor.swagger.ioto be able to select the library to use as well. To consider is that the swagger.io options are completely free, whereas Restlet and APIMATIC are freemium.

尽管对于 GitHub 项目，在将 swagger 转换为 Java 客户端或服务器代码时，由您决定使用哪个库（jersey、jersey2、okhttp-gson 等）。使用 generator.swagger.io，您还可以决定使用哪个库。可能对 editor.swagger.io进行了增强，以便能够选择要使用的库。需要考虑的是 swagger.io 选项是完全免费的，而 Restlet 和 APIMATIC 是免费增值的。

回答by Waseem Hassan

Although swagger generator generates a Java SDK, APIMATIC sdk's are quite mature, detailed, and gives more flexibility that Swagger Gen. You should try APIMATIC sdk generator, you're gonna love it.

尽管 swagger 生成器生成 Java SDK，但 APIMATIC sdk 非常成熟、详细，并且比 Swagger Gen 提供了更多的灵活性。您应该尝试 APIMATIC sdk 生成器，您会喜欢上它的。

回答by zygimantus

Probably the fastest and easiest way to do it:

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

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>

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>

More info here

更多信息在这里

回答by so-random-dude

Just a silly extension to @wing328's answer.

只是@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

If it results in this error (SSL certificate problem)

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

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

Add a -k switch to curl. Example:

将 -k 开关添加到 curl。例子：

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

Response

回复

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

Sending the complete swagger spec JSON payload instead of URL

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

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"
    },
    ...
  }
}

除了使用带有 OpenAPI/Swagger 规范的 URL 的 swaggerUrl，您还可以在 JSON 有效负载中包含规范，例如

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

More Info: Official Doc

更多信息：官方文档