Month: February 2016

ATG · Java · RESTFul · Servlet · Swagger

Swagger Documentation for ATG

prabhukvnLeave a comment

A point of view – not a solution

The mechanism described in http://prabhukvn.com/2016/02/24/swagger-documentation-for-servlet/ works with any java web application as long as all the project class files reside in WEB-INF/classes. But this is not the case with ATG. ATG will read all class files from atglib, hence

Approach 1: Rewrite the Package scanner class so that it will scan the java packages listed in atglib. This package scanner class will be used by swagger servlet to scan classes for swagger specific annotations.

Approach 2: Use the same class loader in above package scanner component which is used by nucleus in ATG.

Java · RESTFul · Servlet · Swagger

Swagger Documentation for Servlet

prabhukvn6 Comments

                         Swagger is tool to document RESTFul services with some simple annotations. This mechanism can be applied even to servlets.

           Read more about the swagger at Swagger.

This document talks about writing swagger documentation for simple servlet.

Step1. Create a simple maven web-app and add following  dependencies in pom.xml

<dependency>
            <groupId>com.wordnik</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.3.11</version>
        </dependency>
        <dependency>
            <groupId>com.wordnik</groupId>
            <artifactId>swagger-servlet_2.10</artifactId>
            <version>1.3.13</version>
            <exclusions>
                <exclusion>
                    <groupId>com.google.guava</groupId>
                    <artifactId>guava</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-servlet</artifactId>
            <version>1.5.7</version>
            <exclusions>
                <exclusion>
                    <groupId>com.google.guava</groupId>
                    <artifactId>guava</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>com.wordnik</groupId>
            <artifactId>swagger-jersey-jaxrs_2.10</artifactId>
            <version>1.3.13</version>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>19.0</version>
        </dependency>
        <dependency>
            <groupId>com.wordnik</groupId>
            <artifactId>swagger-core_2.10</artifactId>
            <version>1.3.13</version>
            <scope>compile</scope>
        </dependency>

Step 2:  Register required servlets in web.xml for processing swagger annotations… as well as hosting swagger docs

a. swagger annotation scanner

<!– swagger servlet reader –>

    <servlet>
        <servlet-name>DefaultServletReaderConfig</servlet-name>
        <servlet-class>com.wordnik.swagger.servlet.config.DefaultServletReaderConfig</servlet-class>
        <init-param>
            <param-name>swagger.resource.package</param-name>
            <param-value>servlet.kvn</param-value>
        </init-param>
        <init-param>
            <param-name>swagger.api.basepath</param-name>
            <param-value>http://localhost:8180/swaggerservlet</param-value>
        </init-param>
        <init-param>
            <param-name>api.version</param-name>
            <param-value>1.0.0</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

b. swagger servlet for hosting documents

<!– swagger api declaration servlet for accessing swagger docs –>
    <servlet>
        <servlet-name>ApiDeclarationServlet</servlet-name>
        <servlet-class>com.wordnik.swagger.servlet.listing.ApiDeclarationServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>ApiDeclarationServlet</servlet-name>
        <url-pattern>/api-docs/*</url-pattern>
    </servlet-mapping>

c. and A simple servlet with swagger documentation

<servlet>
        <servlet-name>MyServlet</servlet-name>
        <display-name>MyServlet</display-name>
        <description></description>
        <servlet-class>servlet.kvn.MyServlet</servlet-class>
    </servlet>

<servlet-mapping>
        <servlet-name>MyServlet</servlet-name>
        <url-pattern>/MyServlet</url-pattern>
    </servlet-mapping>

Step 3: A simple custom servlet with swagger annotations

@Api(value = “/MyServlet”, description = “My Simple Servlet”,produces=”application/json”)
public class MyServlet extends HttpServlet {
    private static final long serialVersionUID = 1L;
      
    /**
     * @see HttpServlet#HttpServlet()
     */
    public MyServlet() {
        super();
        // TODO Auto-generated constructor stub
    }

    /**
     * @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse response)
     */
    @ApiOperation(
            value = “A get operation”,
            notes = “A Simple get operation”,
            httpMethod = “GET”,nickname=”myservlet”)
         public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        // TODO Auto-generated method stub
        System.out.println(“Do Get Method Called.”);
        response.getWriter().write(“{status:Sucess fully called get method}”);
    }

    /**
     * @see HttpServlet#doPost(HttpServletRequest request, HttpServletResponse response)
     */
    protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        // TODO Auto-generated method stub
        response.getWriter().write(“{status:Sucess fully called post method}”);
    }

}

Step 4: build and deploy the war file on any server and access the swagger documentation at http://localhost:port/api-docs/

Java · RESTFul · Swagger

Swagger Documentation for RESTFul Services

prabhukvnLeave a comment

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