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.

swagger-setup

 

 

 

 

 

 

 

 

 

 

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.

swagger-ui-3 swagger-ui-2

swagger-ui-1

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

 

 

 

 

 

 

Advertisements

9 thoughts on “Swagger example with JAVA, Spring, Apache CXF and Jackson

  1. This very easy to follow instructions were extremely useful for quickly getting up to speed and setting up a sample Swagger enabled service.
    My swagger-annotations-1.5.4.jar I used for this is only 16K in size which makes swagger a lightweight documentation solution to future projects.
    Are there any updates needed for io.swagger 1.5.4? On the Swagger config section above, including the file name where this addition is made could make this even more helpful to some newbies. Thank you for taking the time to put this together for us.

    Like

      • Raki says:

        Hi Saurabh,

        Could you please let me know how to integrate with Swagger with Apache CXF JAX-RS application without using spring framework support(with org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet).Most of the links are with Spring with maven but I need the support using CXFNonSpringJaxrsServlet and the required jars with configuration details in the web.xml.

        It would be great If you can help on the same.

        Thanks
        Raki

        Like

    • Kishore says:

      I also have same requirement. Please help us.
      Hi,
      I am trying to configure Swagger ui with Apache CXF RESTful service which does not have web.xml file and webcontent & WEB-INF folders. Through Apache camel service is hitting now. Any one help to integrate swagger with above conditions with step by step. I am new to services, Apache camel, Maven and swagger.
      1) I added two dependencies in pom.xml file
      2) created one swagger configure file in one package(.java file)
      3) I dont have web.xml file so dont know how to format url in browser
      I used http://localhost:{portno]/projectname/api-docs
      http://localhost:portno%5D/projectname/swagger.json
      I did not get result(json) for any url.
      Please help me to configure and url formation to hit

      Like

  2. Raki says:

    Hi Saurabh Agarwal,

    Could you please provide the clear steps to integrate with Swagger into Apache CXF JAX-RS application without spring framework support(using using org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet).

    I have gone through swagger site and your’s blog but I haven’t find any clear steps for configuring swagger using CXFNonSpringJaxrsServlet, most of the links are with Spring-mvc with maven but I need the support using CXFNonSpringJaxrsServlet and the required jars with the configuration steps in web.xml.

    I really facing very hard time with this kind of requirement, It would be very much appreciated if you can help on the same.

    Thanks and Regards,

    –Raki

    Like

  3. Martin says:

    Hi,

    Nice post. Was easy to get up and running. I also have an existing project that does not require spring. Would be great if there is an example for that as well. Lots of tutorials and docs of examples for spring. My environment is Maven, Tomcat, JEE6.

    Like

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 )

Google+ photo

You are commenting using your Google+ 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 )

w

Connecting to %s