Try out with Swagger and Jersey Rest

Recently I had to try out few tools that can generate richer documentation for a Rest API.
I have created a basic demo project that shows off many features of Swagger.
I'm using Tomcat 7.0 , jdk 7.0 , Jersey 2.0 , Swagger 1.5x and eclipse as editor.

Follow the steps and also you can copy the project from my github project.

Step 1: Dependencies 

               <dependency>
   <groupId>javax.servlet</groupId>
   <artifactId>javax.servlet-api</artifactId>
   <version>3.1.0</version>
  </dependency>


  <!-- JAX-RS -->
  <dependency>
   <groupId>javax.ws.rs</groupId>
   <artifactId>javax.ws.rs-api</artifactId>
   <version>${jaxrs.version}</version>
  </dependency>
  <!-- Jersey 2.19 -->
  <dependency>
   <groupId>org.glassfish.jersey.containers</groupId>
   <artifactId>jersey-container-servlet</artifactId>
   <version>${jersey2.version}</version>
  </dependency>
  <dependency>
   <groupId>org.glassfish.jersey.core</groupId>
   <artifactId>jersey-server</artifactId>
   <version>${jersey2.version}</version>
  </dependency>
  <dependency>
   <groupId>org.glassfish.jersey.core</groupId>
   <artifactId>jersey-client</artifactId>
   <version>${jersey2.version}</version>
  </dependency>
  <dependency>
   <groupId>org.glassfish.jersey.media</groupId>
   <artifactId>jersey-media-json-jackson</artifactId>
   <version>${jersey2.version}</version>
  </dependency>

  <!-- Swagger dependencies -->
  <dependency>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-jersey2-jaxrs</artifactId>
   <version>1.5.0</version>
  </dependency>

Step 2: Web.xml config

                <init-param>
   <param-name>jersey.config.server.provider.packages</param-name>
   <param-value>com.kant.rest,io.swagger.jaxrs.listing</param-value>
  </init-param>



Bootstrap class added to configure Swagger
        <servlet>
  <servlet-name>SwaggerBootstrap</servlet-name>
  <servlet-class>com.kant.rest.servlet.Bootstrap</servlet-class>
  <load-on-startup>2</load-on-startup>
 </servlet>

Filter to enable CORS support for tomcat
 <filter>
  <filter-name>CorsFilter</filter-name>
  <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
 </filter>
 <filter-mapping>
  <filter-name>CorsFilter</filter-name>
  <url-pattern>/*</url-pattern>
 </filter-mapping>

Step 3: Use of Swagger Annotations

/**Service endpoint**/

@Api(value = "hello", description = "Endpoint for user management")
@Path("/hello")
public class HelloWorldService {

 @GET
 @Path("/{param}")
 @Produces(MediaType.TEXT_PLAIN)
 @ApiOperation(value = "Returns welcome message.", notes = "Returns a  welcome message for the param name passed.", response = String.class)
 @ApiResponses(value = {
   @ApiResponse(code = 200, message = "Successful retrieval of response", response = String.class),
   @ApiResponse(code = 404, message = "Param passed is not good"),
   @ApiResponse(code = 500, message = "Internal server error") })
 public Response getMsg(@PathParam("param") String msg) {
  if ("bad".equalsIgnoreCase(msg)) {
   return Response.status(Status.BAD_REQUEST).build();
  }
  String output = "Jersey say : " + msg;
  return Response.status(200).entity(output).build();
 }

 @GET
 @Path("/person/{id}")
 @Produces(MediaType.APPLICATION_JSON)
 @ApiOperation(value = "Returns Person.", notes = "Returns a person details for value passed.", response = Person.class)
 @ApiResponses(value = {
   @ApiResponse(code = 200, message = "Successful retrieval of response", response = Person.class),
   @ApiResponse(code = 404, message = "Param passed is not good"),
   @ApiResponse(code = 500, message = "Internal server error") })
 public Response getPerson(@PathParam("id") String id) {
  Person person = new Person();
  if ("1".equals(id)) {
   person.setAge(27);
   person.setEmailId("itsmeshashi@outlook.com");
   person.setFirstName("shashi");
   person.setLastName("kant");
   person.setPhone("532600021");

  } else if (Integer.parseInt(id) < 5) {
   person.setAge(22);
   person.setEmailId("dummayMail@fake.com");
   person.setFirstName("foo");
   person.setLastName("bar");
   person.setPhone("2343-243-234");
  } else
   return Response.status(Status.BAD_REQUEST).build();
  return Response.status(200).entity(person).build();
 }

}

/**Model class**/

@ApiModel(value = "Person", description = "stores person details")
@XmlRootElement
public class Person {
 @XmlElement
 @ApiModelProperty(position = 1, required = true, value = "user's firstname containing only lowercase letters")
 private String firstName;
 @XmlElement
 @ApiModelProperty(position = 2, required = true, value = "user's last name containing only lowercase letters")
 private String lastName;
 @XmlElement
 @ApiModelProperty(position = 3, required = true, value = "email id ")
 private String emailId;
 @XmlElement
 @ApiModelProperty(position = 4, required = true, value = "phone number")
 private String phone;
 @XmlElement
 @ApiModelProperty(position = 5, required = true, value = "user's age")
 private Integer age;

 public String getFirstName() {
  return firstName;
 }

 public void setFirstName(String firstName) {
  this.firstName = firstName;
 }

 public String getLastName() {
  return lastName;
 }

 public void setLastName(String lastName) {
  this.lastName = lastName;
 }

 public String getEmailId() {
  return emailId;
 }

 public void setEmailId(String emailId) {
  this.emailId = emailId;
 }

 public String getPhone() {
  return phone;
 }

 public void setPhone(String phone) {
  this.phone = phone;
 }

 public Integer getAge() {
  return age;
 }

 public void setAge(Integer age) {
  this.age = age;
 }

}

Screenshots:

Notes:

1. Swagger-ui : copy zipped version, unzip and  open ./dist/index.html to launch Swagger UI in a browser. Now Explore your local api. Make sure CORS filter is added to your web.xml according to the server.
2. Swagger editor : try out live demo version and copy your swagger.json to test the editor right away
3. Other Swagger tools .

References:

1. https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5
2. http://stackoverflow.com/questions/16296145/set-cors-header-in-tomcat/18850438#18850438 

Project Page: https://github.com/thekant/jaxrs_swagger_rest_example