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

Question

My scenario is the following.

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

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: cica and the new pet is stored according to the REST API implmentation.

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

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 @RequestMapping in PetApi.java and also has a WebMvcConfiguration.class .

I do not want to have a server-stub. I want to have a client-library for the 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?

Thanks for the answers!

Answer 1

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

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.

For more options on customizing the output of https://generator.swagger.io , please refer to 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)

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

Answer 2

I think that you don't use the right value for the parameter -l of Swagger Codegen (you use spring-mvc which is a server-side technology). You could try to use the 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.

Hope it helps you, Thierry

Answer 3

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-codegen
• generator.swagger.io
• editor.swagger.io
• Restlet
• 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.io to 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.

Answer 4

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>

More info here

Answer 5

Just a silly extension to @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)

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:

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

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

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

More Info: Official Doc

Answer 6

虽然swagger生成器生成Java SDK，但APIMATIC sdk非常成熟，详细，并且提供了更多Swagger Gen的灵活性。您应该尝试使用API​​MATIC sdk生成器，您会喜欢它。