Spring MVC and Swagger. Generating documentation for your RESTful web services - PART 1

Automating your RESTful web services documentation Using Spring MVC with Swagger for generating it


Part 1 - Setting up the WAR and spring configuration


1.- Introduction


Through this simple tutorial I will be developing a simple web application using the following technologies :

The main goal of this tutorial is to illustrate how the swagger documentation framework can be integrated into a spring mvc application.

2.- The Database Model

In this tutorial we will be using a very simple model consisting of 1 table :


3.- Creating the maven project structure

There are a few of Spring archetypes when creating java web applications but I find them oversized for this simple tutorial so I will use here the org.codehaus.mojo.archetypes.webapp-javaee6 archetype :


mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=webapp-javaee6 -DpackageName=com.ufasoli.tutorial.swagger.springmvc -DgroupId=com.ufasoli.tutorial -DartifactId=swagger-spring-mvc -Dversion=1.0

This should generate a pretty standard maven WAR project structure

Note : You should adapt your groupId and artifactId according to your config.

4.- Dependencies

In your pom.xml file add the following dependencies that we are going to need for our project : 


...
 
        ${project.build.directory}
        UTF-8
        3.2.1.RELEASE
        1.8.0.10
    

    
        
            javax
            javaee-web-api
            6.0
            provided
        

        
            com.mangofactory
            swagger-springmvc
            0.5.2
        

        
            org.springframework
            spring-core
            ${version.spring}
        

        
            org.springframework
            spring-jdbc
            ${version.spring}
        
        
            org.springframework
            spring-expression
            ${version.spring}
        
        
            org.springframework
            spring-web
            ${version.spring}
        
        
            org.springframework
            spring-webmvc
            ${version.spring}
        

        
            org.springframework
            spring-beans
            ${version.spring}
        
        
            org.hsqldb
            hsqldb
            ${version.hsqldb}
        

    

...

5.- Spring Configuration

There are many schools when it comes to creating spring context files
I usually create a spring-web.xml file under the src/main/webapp/WEB-INF folder that I will use as my web application context and an applicationContext.xml file under src/main/resources/META-INF/spring that will be my application context.

5.1.- Configuring the Application Context (applicationContext.xml)
5.1.1- Setting up the classpath scanner
5.1.2- Setting up the database

Spring has a pretty nifty way to step up an in-memory database.You can provide a list of SQL scripts that will be executed when the database is started

I have written 2 SQL scripts one for creating the database and another one to have some sample data inserted in the database

This scripts can be found under src/main/resources/sql :

CREATE TABLE BOOKS (id VARCHAR NOT NULL, title VARCHAR NOT NULL, author VARCHAR NOT NULL, publicationYear INTEGER, comment VARCHAR, PRIMARY KEY(id))

INSERT INTO BOOKS VALUES ('1', 'A Game of Thrones', 'George R. R. Martin', 1996, 'n.c.');
INSERT INTO BOOKS VALUES ('2', 'A Clash of Kings', 'George R. R. Martin', 1998, 'n.c.');
INSERT INTO BOOKS VALUES ('3', 'A Storm of Swords', 'George R. R. Martin', 2000, 'n.c.');
INSERT INTO BOOKS VALUES ('4', 'A Feast for Crows ', 'George R. R. Martin', 2005, 'n.c.');
INSERT INTO BOOKS VALUES ('5', 'A Dance with Dragons', 'George R. R. Martin', 2011, 'It was about time!');
INSERT INTO BOOKS VALUES ('6', 'The Winds of Winter', 'George R. R. Martin', 2014, 'If we are lucky!');
INSERT INTO BOOKS VALUES ('7', 'A Dream of Spring', 'George R. R. Martin', 2100, 'oh c`mon');

We will now configure the applicationContext.xml file using a HSQL in-memory database and instruct spring to execute the SQL scripts in a predefined order as well as bootstrap Spring's JDBC template class which is an utility class that simplifies the use of JDBC

Below is how the applicationContext.xml file should look like :

With this configuration every time the application is started the database will be bootstraped and some sample data will be inserted

5.2.- Configuring the Web Application Context (spring-web.xml)

The Web Application context extended Application Context which is designed for work with the standard javax.servlet.ServletContext so it's able to communicate with the container.

5.2.1- Setting up the classpath scanner & the Spring MVC configuration

I will not go into the details of Spring but to sumarize the classpath scanner for the web application context will essentially pick up the controllers and register them in the context whereas the Spring MVC configuration will define how controllers should by discovered and how URLs should be handled
5.3.- Configuring the web.xml descriptor

It's now time to tell our web app to use spring-mvc. For this to happen we need to edit the web.xml file under src/main/webapp/WEB-INF and add the spring configuration : 


     

    Spring MVC Swagger integration

      
        
            index.html
        

    
    
        contextConfigLocation
        classpath:/META-INF/spring/applicationContext.xml
    

    
    
        org.springframework.web.context.ContextLoaderListener
    

    
    
        spring-servlet
        org.springframework.web.servlet.DispatcherServlet
        
        
            contextConfigLocation
            /WEB-INF/spring-web.xml
        
        1
    

    
    
        spring-servlet
        /

6.- Taking it for a spin

If everything goes according to plan we should be able to take our application for a spin with a simple hello world!

6.1.- Creating the HelloWorld Controller

Create a HelloWorldService.java file under src/main/java/ and the package of your choice 

package com.ufasoli.tutorial.swagger.springmvc.web.services;

import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import javax.servlet.http.HttpServletResponse;

@Controller
@RequestMapping(value = "/hello", produces = MediaType.TEXT_PLAIN_VALUE)
public class HelloWorldService {

    @RequestMapping( produces = MediaType.TEXT_PLAIN_VALUE, method = RequestMethod.GET)
    public @ResponseBody String sayHelloWorld(HttpServletResponse response){

        return "Hello World!";
    }
}

With this configuration spring will register your hello-world controller under :

  ${context.root}/hello
6.2.- Configuring jetty and running the app

We are almost there, the last thing we need to do is to configure our embedded Jetty server

Head to your pom.xml file 

...


  
    ...
     
      org.mortbay.jetty
      maven-jetty-plugin
      6.1.26
      
        
          /spring-mvc-swagger-tutorial
        
        0
        
          
             9090
             60000
           
          
       
     
     ...


...

This configuration will start a jetty server under the port 9090 and deploy my application under the /spring-mvc-swagger-tutorial context-root

6.3.- Running the app

Head to your command line or favorite IDE and run the following maven goal 

   mvn jetty:run

Wait for your server to start, you should see a message similar to: 

...
  2013-06-06 15:23:50.668:INFO::jetty-6.1.26
2013-06-06 15:23:50.825:INFO::No Transaction manager found - if your webapp requires one, please configure one.
2013-06-06 15:23:51.135:INFO:/spring-mvc-swagger-tutorial:Initializing Spring root WebApplicationContext
log4j:WARN No appenders could be found for logger (org.springframework.web.context.ContextLoader).
log4j:WARN Please initialize the log4j system properly.
log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
2013-06-06 15:23:51.957:INFO:/spring-mvc-swagger-tutorial:Initializing Spring FrameworkServlet 'spring-servlet'
2013-06-06 15:23:53.511:INFO::Started SelectChannelConnector@0.0.0.0:9090
[INFO] Started Jetty Server

Now crack open your favorite browser and head to : 

http://localhost:9090/spring-mvc-swagger-tutorial/hello

And if the programming Gods are good you should get your well deserved greeting

6.- Wrapping-up part 1

So that's it for part 1 of the tutorial. On the second part we will create a more complex controller and see how to integrate the Swagger framework into our project

You can find this sample application over at github :

Swagger - Spring MVC tutorial sample application code
at
Labels: , , , , ,

1 comment:

Subscribe to: Post Comments (Atom)

OSX show used ports or listening applications with their PID

On OSX you can display applications listening on a given port using the lsof the commands described below will show listening application...