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
