Java · RESTFul · Swagger

Swagger Documentation for RESTFul Services

Swagger has come with an easy way to Document and Test RESTFul services with an ease. Swagger has come up with a bunch of Annotations which will be simply used to document and test web services.

Here, I described how to document rest services with Swagger in simple steps.

For mode details on swagger, please visit Swagger.

Visit Swagger Annotations for complete understanding of various annotations.

What we used,

  1. JDK 6 or Above
  2. Rest Services using Jersey 1.19
  3. Maven for dependency management.
  4. Jboss 6.1 eap. we can use any server.
  5. Eclipse Luna, an optional. can be any latest version.

Step1 :

Create java web project (dynamic web project in eclipse)  Or use any webapp archives in maven.

Step2

Go to web.xml to define jersey and swagger servlets,

<!-- Jersey Servlt -->
  <servlet>
    <servlet-name>rest</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
      <param-name>jersey.config.server.provider.packages</param-name>
      <param-value>     
             io.swagger.jaxrs.json,io.swagger.jaxrs.listing,com.wordnik.swagger.jersey.listing,jersey.swagger.restswagger
        </param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>

And Swagger Servlet

<!--  Swagger Servlet -->
<servlet>
<servlet-name>Jersey2Config</servlet-name>
<servlet-class>io.swagger.jaxrs.config.DefaultJaxrsConfig</servlet-class>
<init-param>
<param-name>api.version</param-name>
<param-value>1.0.0</param-value>
</init-param>
<init-param>
<param-name>swagger.api.basepath</param-name>
<param-value>http://localhost:8180/RestSwagger/rest</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>

Step 3.

Create a RestFul services according to Jersey notations,

@Path("/company")
@Api(value="/company")
@Produces({"application/json"})
public class MyResource {

/**
* An In Memory Map to hold employee data
*/
public static Map<String, User> employeeList = new HashMap<String, User>();

/** Method processing HTTP GET requests, producing "application/json" MIME media
* type.
* @return String that will be send back as a response of type "application/json".
*/
@GET
@Path("/")
@Produces("application/json")
public String getIt() {

Gson gson = new Gson();
User user = new User();
user.setEmail("prabhukvn@gmail.com");
user.setName("prabhu");
employeeList.put("prabhu", user);
return gson.toJson(user);
}

 

Step 4.

Use Swagger annotations like @Api, @ApiOperation as described above

Step 5.

Copy the “dist” folder from swagger-UI into webapps

step 6.

Change the swagger.jsson url in index.html which is residing in “dist” folder

<script type="text/javascript">
$(function () {
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://localhost:8180/RestSwagger/rest/swagger.json";
} …

Step 7.

Deploy the code in a server. This code tested on jbosseap6.1 development version.

Step 8.Access the swagger UI with following link

http://localhost:8180/RestSwagger/dist/index.html

Here, how it will look like in swagger

 

Rest-swaggerUI

 

 

 

 

 

Rest-swaggerUI2

 

 

Download Reference Code

https://drive.google.com/open?id=0B42U3eIWbBK6UEtqUE9xZWd4eTA

Check the Running Site with above code

http://jboss7thoughts-mias.rhcloud.com/RestSwagger/dist/index.html

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s