ATG · Java · RESTFul · Servlet · Swagger

Swagger Documentation for ATG

A point of view – not a solution

The mechanism described in https://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

                         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/