Swagger example with JAVA, Spring, Apache CXF and Jackson

As I try to build more and more SDN applications on top of OpenDaylight and other SDN Controllers, there was a common need to give REST NBI document to other users to consume the REST API’s of my newly built apps.

So the questions I was trying to solve were:

• How to say to clients how to use a REST API? There’s no real standard or at least de-facto standard to expose a REST contract.
• Write manual documentation or let some tool generate it for me.
• My written-by-hand web service documentation isn’t ever going to be up-to-date.
• I was more interested in writing the services THAN its documentation

Hence I started evaluating a common REST API documentation frameworks and finally Swagger stuck me.

So what is Swagger?

• Swagger is a specification for documenting REST API. As an application developer, I write web services using your favorite framework.
• Swagger scans my code and exposes the documentation on some URL.
• Any client can consume this URL (which comes as XML or JSON documents) and learn how to use your REST web services.
• Client now knows which HTTP methods to call on which URL, which input documents to send, which status code to expect, etc.
• Swagger is a specification and supports a wide range of frameworks.

I have created a simple project to help everyone see how to use Swagger on top of Spring, Apache CXF & Jackson.

How To Guide

1. Project Setup:

Please see the visual of my project setup, source code of which is available at my git here.

 

 

 

 

 

 

 

 

 

 

2. REST API

I have written a very simple REST API for this demo, which has annotations like below

import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;

@Path("/user")
@Api(value = "/user", description = "User REST for Integration Testing")
public interface UserService {

    @GET
    @Path("/getUser/{username}")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @ApiOperation(value = "Get user details", response = User.class)
    public User getUser(@PathParam("username") String username);

    @POST
    @Path("/saveUser")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @ApiOperation(value = "Save user details", response = User.class)
    public User getUser(User user);
}

Interesting thing to note here is the @Api & @ApiOperation tags, which is a swagger tag and helps Swagger scan the elements needed and create the documentation. I have used minimal options from Swagger.

3. Swagger Config

Now to make this all work, and let swagger know of the packages to scan, URL to publish etc, below configuration is needed.

    <!-- Swagger API listing resource -->
    <bean id="swaggerResourceJSON" 
        class="com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON" />

    <!-- Swagger writers -->
    <bean id="resourceWriter"
        class="com.wordnik.swagger.jaxrs.listing.ResourceListingProvider" />
    <bean id="apiWriter"
        class="com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider" />

    <jaxrs:server address="/sw" id="swagger">
        <jaxrs:serviceBeans>
            <ref bean="swaggerResourceJSON" />
        </jaxrs:serviceBeans>
        <jaxrs:providers>
            <ref bean="resourceWriter" />
            <ref bean="apiWriter" />
        </jaxrs:providers>
    </jaxrs:server>

    <bean id="swaggerConfig" class="com.wordnik.swagger.jaxrs.config.BeanConfig">
        <property name="resourcePackage" value="com.sau.swagger.intg" />
        <property name="version" value="2.0" />
        <property name="basePath" value="http://localhost:8080/SwaggerUI-Integration/rest" />
        <property name="title" value="Swagger UI Integration Sample" />
        <property name="description"
            value="Swagger UI Integration Sample for demonstrating its working." />
        <property name="contact" value="saurabh29july@gmail.com" />
        <property name="scan" value="true" />
    </bean>

4. Swagger GUI

Once above is done and you deploy the project on a web server (tomcat etc), access the URL (http://localhost:8080/SwaggerUI-Integration/nbiDocs/index.html) to see the interactive UI in action.

If you need a skeleton project to get this working or for reference, please download the source from my git here.