Tag: Experience

Swagger (hyperlink to this site http://swagger.io) provides the most simple, yet powerful representation of your API’s. Most of the cases what you would want to do after generating a thorough set of API’s is to have a simple Java client to access these – and Swagger comes to rescue here, by providing an open source tool just to do that.

Here in this article, we would be using Swagger Codegen tool to generate our Client side code. You can simply download the Swagger Codegen zip file from this location (link to this site https://github.com/swagger-api/swagger-codegen)

Open the link and then click on the green coloured button ‘Clone or download’ and from the drop-down click on ‘Download Zip’.

How to build Swagger Codegen?

After downloading the source zip file from the site above, you would have to build this project. You could use either ANT or MAVEN to build the project, but the downloaded file is a MAVEN project. Hence there is a prerequisite that you need to have MAVEN installed and configured on the system.

Now with all the pre-requisite being handled and answered, let’s get down to business in building the Swagger Codegen project that you’ve downloaded in the last step.

• Extract the zip file to a location which you would be referring to from a command line tool
• Fire the following command to on a command prompt to build the project
• mvn package

How to generate Client-side code using Swagger Codegen?

The above step would download all the requisite dependencies on to your local system, which is something that MAVEN handles on its own. Along with the dependencies, it will also generate the needed modules under this directory which will be used in the steps below. With the above step done, you’ll need to follow the steps below to get the client-side code generated using Swagger Codegen.

• There are a plenty of supported languages to choose from (like Clojure, Groovy, Haskell, Java) but I will try to keep this article targeted to be used with JAVA.
• With the choice made above, all you need to have is a YAML or a JSON input file, which would be used to represent the API using Swagger.
• You can take any of the sample YAML/JSON files provided by Swagger themselves, or write your own YAML by hand and use the same as the input
  • You can use Swagger editor (link to this site: http://editor.swagger.io/#/) to write your own YAML / JSON input files.
  • If you decide to go by having your own YAML / JSON input file, then this Swagger specifications (link to this site: http://swagger.io/specification/) should be followed with due respect.
• From the same location as above, fire the command below:
  • This command will work if you are using any of the sample YAML / JSON files provided by Swagger itself

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

     

• The following command will work if you are using any of your own input YAML file to generate client-side code with an assumption that the YAML file is placed under the folder structure shown in the command below.

• java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate
  
          -i modules/swagger-codegen-cli/target/sample_api.yaml
  
          -l java
  
          -o samples/client/java
  
  

   

  Choose whichever the case as you like and it will generate a java project with the package structure as mentioned in the command above with the -o

How to use the generated client-side code?

Now that the toughest part of the task being completed, you could use the generated client side code in whichever way that you wish.

• You could import this code as a Java project into any IDE of your choice or you could very well zip the project as a JAR and ship to it whoever wants to gain access to your API’s that are generated.
• If you take a look into the code that has been created, you would find a package named ‘io.swagger.client.api’ and under which you’d find 3 classes. Using these you would be able to do whatever you want with the API specification that you have.
• A sample code to say update a pet and display it’s name can be done using the following code.

package io.swagger.test;

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

import org.w3c.dom.ls.LSException;

import io.swagger.client.ApiException;
import io.swagger.client.api.*;

public class test 
{
  public static void main(String[] args) throws IOException
  {
    List<String> status = new ArrayList<String>();
    status.add("sold");
    PetApi pet = new PetApi();

    try 
    {
      pet.updatePetWithForm("1", "nicky", "available");
      System.out.println(pet.getPetById((long) 1).getName());
    }
    catch (ApiException e) 
    {
      e.printStackTrace();
    }
  }
}