Show off your spring web services through swagger, Just like that…

A backend blackhole services developer can become a shooting star with swagger.  This is like a new super power that can take you to a whole new level. I have been trying to get deeper into it. I think i can discuss some basic stuff to kick start you on this.

Nirvana hits when you realize that you can even try out your web services right through this user interface.Holiness all the way.

Swagger: http://swagger.wordnik.com/

Based on the beautiful and easy to strap spring-mvc work from MartyPitt:

https://github.com/martypitt/swagger-springmvc-example

Step 1: Maven dependencies

<!-- Swagger for API Documentation -->
 <dependency>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok</artifactId>
 <version>0.10.8</version>
 <scope>provided</scope>
 </dependency>
 <dependency>
 <groupId>com.mangofactory</groupId>
 <artifactId>swagger-springmvc</artifactId>
 <version>0.6.6</version>
 </dependency>
 <dependency>
 <groupId>com.fasterxml.jackson.core</groupId>
 <artifactId>jackson-databind</artifactId>
 <version>2.1.1</version>
 </dependency>
 <dependency>
 <groupId>com.fasterxml.jackson.core</groupId>
 <artifactId>jackson-annotations</artifactId>
 <version>2.1.1</version>
 </dependency>
 <dependency>
 <groupId>com.fasterxml.jackson.core</groupId>
 <artifactId>jackson-core</artifactId>
 <version>2.1.1</version>
 </dependency>
 <dependency>
 <groupId>joda-time</groupId>
 <artifactId>joda-time</artifactId>
 <version>2.1</version>
 </dependency>
 <dependency>
 <groupId>org.springframework.hateoas</groupId>
 <artifactId>spring-hateoas</artifactId>
 <version>0.3.0.RELEASE</version>
 </dependency>
 </dependencies>

2. Include a swagger.properties file in your resources folder

documentation.services.basePath=http://localhost:8080/myspringwebapp 
documentation.services.version=1.0

3. Add the configuration for the swagger to discover all the a=spring based annotations and create the api docs service

<context:component-scan base-package="com.myspringwebapp.generic" />
 <mvc:annotation-driven/>
 <context:annotation-config/>
<bean id="propertyPlaceholderConfigurer"
 class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
 <property name="systemPropertiesModeName" value="SYSTEM_PROPERTIES_MODE_OVERRIDE" />
 <property name="locations">
 <list>
 <value>classpath:swagger.properties</value>
 </list>
 </property>
 </bean>
<mvc:default-servlet-handler/>
<!-- To enable @RequestMapping process on type level and method level -->
 <bean class="org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping" />
 
 <!-- creates a controller at /api-docs from this uri, which serves swagger's raw documentation in JSON format. -->
 <bean id="documentationConfig" class="com.mangofactory.swagger.configuration.DocumentationConfig"></bean>


4. Add the swagger-ui dependencies and the relevant css, js, and html pages. I had to update the swagger-ui javascript but am sure the one shared by martypitt also works as i tried it too.

https://github.com/martypitt/swagger-springmvc-example/tree/master/src/main/webapp

5. Voila, just run this application in the container you are in love with

Test it out locally
http://localhost:8080/myspringwebapp/api-docs
The above url should return a list of controllers available in your spring mvc project
Doc UI: 
http://localhost:8080/myspringwebapp/index.html
The html has all that it takes to read the api and beautify it, such that you can read, play and do everything you could with it.

Swagger was smooth and as a project it was amazing to use and showcase the beautiful API doc to stakeholders. If you are just curious then take a peek at the beauty in the attached screen shot of a GET and a POST interface on my REST user spring controllers.

A beautiful proof of the working api doc

A beautiful proof of the working api doc