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/

Advertisements

3 thoughts on “Swagger Documentation for Servlet

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