Document Spring based Restful API using Swagger

|
| By Webner

Swagger is a very powerful tool to generate documentation of your Rest based web services API containing Spring annotations. You don’t need to add any type of comments to your code to generate documentation. It will pick the Spring annotations and will generate the documentation for you. Below are the steps that you have to follow to document your api with Swagger :

1.  Add below specified maven dependencies to your project :

<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-core</artifactId>
<version>${swagger.core}</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${swagger.annotation}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox.swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox.swagger.version}</version>
</dependency>

Version specified inside maven properties element in the POM  file :

<springfox.swagger.version>2.6.1</springfox.swagger.version>
<swagger.annotation>1.5.9</swagger.annotation>
<swagger.core>1.5.10</swagger.core>
<spring.version>4.0.4.RELEASE</spring.version>
<hibernate.version>4.3.5.Final</hibernate.version>

2.  Add SwaggerConfiguration.java( you can use any class name) class to your project and add below code to it :

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(
           RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();
    }
}

3.  Match you application.xml file with content below and if anything is missing add it to your file :

<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
        http://www.springframework.org/schema/beans     
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.springframework.org/schema/context 
        http://www.springframework.org/schema/context/spring-context-3.0.xsd
        http://www.springframework.org/schema/mvc
        http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
<context:component-scan base-package="add your base package here" />
<context:annotation-config />
<mvc:annotation-driven />
<mvc:resources mapping="swagger-ui.html"   location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
</beans>

4.  After completing above changes, compile and deploy your project.  

Type url : https://your api url /swagger-ui.html  , You will see the swagger api interface as below :

1

All the above controller classes will be represented here and hyperlinked to the methods defined in the respective controller class.

For example, customer Services.( for me), on clicking it  you will see all its methods :

2

Leave a Reply

Your email address will not be published. Required fields are marked *