Swagger ( An easy way to document your Rest API) Tutorial

Hi,

In this blog, I will share how you can use Swagger to document your Rest services/api.

Swagger is an open source software that can come handy and is easy to use/configure if you are looking to document your Rest APIs. During development with multiple developers in a distributed team it can also come handy to have a visibility on Rest Services developed by Team.

This article will focus on basic configuration.For sample JSON Rest web service have referred to an example from http://avaldes.com/spring-restful-web-service-example-with-json-and-jackson-using-spring-tool-suite/. It's a good site with info.

Step-1: Make sure you have a Restful webservice up and running. I tried using an example from
http://avaldes.com/spring-restful-web-service-example-with-json-and-jackson-using-spring-tool-suite/
It can be downloaded from http://avaldes.com/?wpdmdl=4550
so before we move forward,check http://localhost:8080/<context-name>/issuers is returning a JSON response.

Step-2: Edit the pom.xml and add swagger dependencies.

<!-- Swagger Starts -->
      <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.1.2</version>
      </dependency>
      <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.1.2</version>
       </dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.3.11</version>
</dependency>
<!-- Swagger Ends   -->

Step-3: Edit the pom.xml and add jackon dependencies.(Jackson is a multi-purpose Java library for processing JSON data format.)
             <!-- Jackson -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson.databind-version}</version>
</dependency>
Step-4 Update the project..do a maven clean and install. You should get all the jars and have an error free project now.

Step-5 Now lets instrument the Rest service so that swagger can be used . Add @ApiOperation annotation to your API. So in the example code for RestController below update is done.

sample:
@RequestMapping(value="/issuer/{ticker}", method=RequestMethod.GET)
@ApiOperation(value = "API getIssuerByTicker", notes = "Returns a issuer", response=Issuer.class)
@ResponseBody
public Issuer getIssuerByTicker(@PathVariable("ticker") String ticker) {
Issuer myIssuer = issuers.get(ticker);

if (myIssuer != null) {
logger.info("Inside getIssuerByTicker, returned: " + myIssuer.toString());
} else {
logger.info("Inside getIssuerByTicker, ticker: " + ticker + ", NOT FOUND!");
}
return myIssuer;
}
Similarly add annontations to other webservice methods with appropiate value,notes and response.
(http://docs.swagger.io/swagger-core/apidocs/com/wordnik/swagger/annotations/ApiOperation.html)

Step-6 In web.xml, add the below
<servlet>
   <servlet-name>staticServlet</servlet-name>
   <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
   <load-on-startup>1</load-on-startup>
 </servlet>

 <servlet-mapping>
    <servlet-name>staticServlet</servlet-name>
    <url-pattern>*.html</url-pattern>
    <url-pattern>*.js</url-pattern>
    <url-pattern>*.css</url-pattern>
    <url-pattern>*.jpg</url-pattern>
    <url-pattern>*.png</url-pattern>
    <url-pattern>*.gif</url-pattern>
  </servlet-mapping>

Step-7 Now you are all set, run your project and check..
http://localhost:8080/<context-name>/issuers
it should be working
now check
http://localhost:8080/<context-name>/v2/api-docs
this should return swagger instrument json
now access swagger ui to present this instrumented json to get a nice looking view of your rest api documentation
http://localhost:8080/<context-name>/swagger-ui.html

Thank you..