Integrate RESTful Web Service with Swagger

Introduction

Spring Boot makes developing RESTful services ridiculously easy and using Swagger makes documenting your RESTful services easy. Building a back-end API layer introduces a whole new area of challenges that goes beyond implementing just endpoints. You now have clients which will now be using your API. Your clients will need to know how to interact with your API. API documentation should be structured so that it’s informative, succinct, and easy to read. But best practices on, how you document your API, its structure, what to include and what not to is altogether a different subject that I won’t be covering here.

This article describe how to integrate Spring Boot Rest API with Swagger and will show the documentation and implementation.

Overview

In this article I am using existing Spring Boot Rest API sample. Please follow my previous article to build Spring Boot Rest API.

I am just going to integrate with Swagger by using existing Spring Boot API. We need to follow below steps to Integrate.

Ø  Add Swagger Dependencies.

Ø  Create Swagger Configuration Class.

Ø  Add Swagger notations to Controller Class.

Ø  Test the Application.

Add Swagger Dependencies:

For the existing application we need to add swagger related dependencies.

Open pom.xml add below two dependencies.

		
			io.springfox
			springfox-swagger-ui
			2.6.1
			compile
		

		
			io.springfox
			springfox-swagger2
			2.6.1
			compile
		

Create Swagger Configuration:

We should create a Swagger configuration class for swagger documentation details. A Springfox Docket instance provides the primary API configuration with sensible defaults and convenience methods for configuration.

Create a Java class name as ‘SwaggerConfig’ and add below code.

package com.eai.integration.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	@Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()                 .apis(RequestHandlerSelectors.basePackage("com.eai.integration.controller"))
                .paths(regex("/api.*"))
                .build();
    }
	
	
	public ApiInfo apiDetails(){
		ApiInfo apiInfo = new ApiInfo(
                "Customer REST API",
                "Customer REST API for Customer Service",
                "1.0",
                "Terms of service",
                new Contact("Ameer Basha", "http://www.global-techhub.com/", "ameerg.eai@gmail.com"),
                "Apache License Version 2.0",
                "http://www.global-techhub.com/");
        return apiInfo;
		
	}
}

In this configuration class, the @EnableSwagger2 annotation enables Swagger support in the class. The select() method called on the Docket bean instance returns an ApiSelectorBuilder, which provides the apis() and paths() methods that are used to filter the controllers and methods that are being documented using String predicates.

In the code, the RequestHandlerSelectors.basePackage predicate matches the com.eai.integration.controller base package to filter the API. The regex parameter passed to paths()acts as an additional filter to generate documentation only for the path starting with /api.

Add Swagger notations to Controller:

We can use the @Api annotation on our controller class to describe our API. Add below annotations in controller class.

package com.eai.integration.controller;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import com.eai.integration.bo.Customer;
import com.eai.integration.repository.CustomerRepository;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

/**
 * @author Ameer
 *
 */
@RestController
@RequestMapping("/api")
@Api(value="Customer API", description="Operations to perform Customer Service activities")
public class CustomerController {
	@Autowired
	private CustomerRepository customerRepository;
	
	
	@ApiOperation(value = "View a Customer", response = Customer.class)
	@ApiResponses(value = {
	        @ApiResponse(code = 200, message = "Successfully retrieved list"),
	        @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
	        @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
	        @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
	}
	)
	@RequestMapping(value = "/customer/{customerID}", method = RequestMethod.GET, produces = {MediaType.APPLICATION_JSON_VALUE})
    public @ResponseBody Customer getCustomer(@PathVariable Integer customerID) {
		Customer customer = customerRepository.findByCustomerID(customerID);
        return customer;
    }
	
	@ApiOperation(value = "Create a new Customer", response = String.class)
	@RequestMapping(value = "/customer", method = RequestMethod.POST, produces = {MediaType.APPLICATION_JSON_VALUE})
    public @ResponseBody String createCustomer(@RequestBody Customer customer) {
		customerRepository.save(customer);
		String message = "Customer Created successfully";
        return message;
    }
}

For each of our operation endpoints, we can use the @ApiOperation annotation to describe the endpoint and its response type.

Swagger 2 also allows overriding the default response messages of HTTP methods. You can use the @ApiResponse annotation to document other responses, in addition to the regular HTTP 200 OK.

Test the Application:

Now start the application, right click on Integration-API-Customer à Run As à Spring Boot App.

Now we can see application started message in log.

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v1.5.7.RELEASE)

2017-10-15 13:15:04.744  INFO 2200 --- [           main] com.eai.integration.CustomerApplication  : Starting CustomerApplication on AMEER with PID 2200 (started by Ameer in C:\WS\SPRING BOOT\BLOGGER\Integration-API-Customer)
2017-10-15 13:15:04.748  INFO 2200 --- [           main] com.eai.integration.CustomerApplication  : No active profile set, falling back to default profiles: default
2017-10-15 13:15:04.795  INFO 2200 --- [           main] ationConfigEmbeddedWebApplicationContext : Refreshing org.springframework.boot.context.embedded.AnnotationConfigEmbeddedWebApplicationContext@1e67a849: startup date [Sun Oct 15 13:15:04 IST 2017]; root of context hierarchy
2017-10-15 13:15:05.998  INFO 2200 --- [           main] o.s.b.f.s.DefaultListableBeanFactory     : Overriding bean definition for bean 'managementServletContext' with a different definition: replacing [Root bean: class [null]; scope=; abstract=false; lazyInit=false; autowireMode=3; dependencyCheck=0; autowireCandidate=true; primary=false; factoryBeanName=org.springframework.boot.actuate.autoconfigure.EndpointWebMvcHypermediaManagementContextConfiguration; factoryMethodName=managementServletContext; initMethodName=null; destroyMethodName=(inferred); defined in class path resource [org/springframework/boot/actuate/autoconfigure/EndpointWebMvcHypermediaManagementContextConfiguration.class]] with [Root bean: class [null]; scope=; abstract=false; lazyInit=false; autowireMode=3; dependencyCheck=0; autowireCandidate=true; primary=false; factoryBeanName=org.springframework.boot.actuate.autoconfigure.EndpointWebMvcAutoConfiguration; factoryMethodName=managementServletContext; initMethodName=null; destroyMethodName=(inferred); defined in class path resource [org/springframework/boot/actuate/autoconfigure/EndpointWebMvcAutoConfiguration.class]]
2017-10-15 13:15:06.623  INFO 2200 --- [           main] trationDelegate$BeanPostProcessorChecker : Bean 'org.springframework.transaction.annotation.ProxyTransactionManagementConfiguration' of type [org.springframework.transaction.annotation.ProxyTransactionManagementConfiguration$$EnhancerBySpringCGLIB$$107b837e] is not eligible for getting processed by all BeanPostProcessors (for example: not eligible for auto-proxying)
2017-10-15 13:15:07.046  INFO 2200 --- [           main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat initialized with port(s): 8080 (http)
2017-10-15 13:15:07.059  INFO 2200 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2017-10-15 13:15:07.060  INFO 2200 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet Engine: Apache Tomcat/8.5.20
2017-10-15 13:15:07.427  INFO 2200 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2017-10-15 13:15:07.427  INFO 2200 --- [ost-startStop-1] o.s.web.context.ContextLoader            : Root WebApplicationContext: initialization completed in 2636 ms
2017-10-15 13:15:07.734  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.ServletRegistrationBean  : Mapping servlet: 'webServlet' to [/h2/*]
2017-10-15 13:15:07.735  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.ServletRegistrationBean  : Mapping servlet: 'dispatcherServlet' to [/]
2017-10-15 13:15:07.739  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'metricsFilter' to: [/*]
2017-10-15 13:15:07.739  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'characterEncodingFilter' to: [/*]
2017-10-15 13:15:07.739  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'hiddenHttpMethodFilter' to: [/*]
2017-10-15 13:15:07.739  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'httpPutFormContentFilter' to: [/*]
2017-10-15 13:15:07.740  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'requestContextFilter' to: [/*]
2017-10-15 13:15:07.740  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'webRequestLoggingFilter' to: [/*]
2017-10-15 13:15:07.740  INFO 2200 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'applicationContextIdFilter' to: [/*]
2017-10-15 13:15:08.164  INFO 2200 --- [           main] j.LocalContainerEntityManagerFactoryBean : Building JPA container EntityManagerFactory for persistence unit 'default'
2017-10-15 13:15:08.178  INFO 2200 --- [           main] o.hibernate.jpa.internal.util.LogHelper  : HHH000204: Processing PersistenceUnitInfo [
	name: default
	...]
2017-10-15 13:15:08.288  INFO 2200 --- [           main] org.hibernate.Version                    : HHH000412: Hibernate Core {5.0.12.Final}
2017-10-15 13:15:08.289  INFO 2200 --- [           main] org.hibernate.cfg.Environment            : HHH000206: hibernate.properties not found
2017-10-15 13:15:08.290  INFO 2200 --- [           main] org.hibernate.cfg.Environment            : HHH000021: Bytecode provider name : javassist
2017-10-15 13:15:08.357  INFO 2200 --- [           main] o.hibernate.annotations.common.Version   : HCANN000001: Hibernate Commons Annotations {5.0.1.Final}
2017-10-15 13:15:08.539  INFO 2200 --- [           main] org.hibernate.dialect.Dialect            : HHH000400: Using dialect: org.hibernate.dialect.H2Dialect
2017-10-15 13:15:09.238  INFO 2200 --- [           main] org.hibernate.tool.hbm2ddl.SchemaExport  : HHH000227: Running hbm2ddl schema export
2017-10-15 13:15:09.250  INFO 2200 --- [           main] org.hibernate.tool.hbm2ddl.SchemaExport  : HHH000230: Schema export complete
2017-10-15 13:15:09.272  INFO 2200 --- [           main] j.LocalContainerEntityManagerFactoryBean : Initialized JPA EntityManagerFactory for persistence unit 'default'
2017-10-15 13:15:10.066  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/api/customer],methods=[POST],produces=[application/json]}" onto public java.lang.String com.eai.integration.controller.CustomerController.createCustomer(com.eai.integration.bo.Customer)
2017-10-15 13:15:10.067  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/api/customer/{customerID}],methods=[GET],produces=[application/json]}" onto public com.eai.integration.bo.Customer com.eai.integration.controller.CustomerController.getCustomer(java.lang.Integer)
2017-10-15 13:15:10.068  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/v2/api-docs],methods=[GET],produces=[application/json || application/hal+json]}" onto public org.springframework.http.ResponseEntity springfox.documentation.swagger2.web.Swagger2Controller.getDocumentation(java.lang.String,javax.servlet.http.HttpServletRequest)
2017-10-15 13:15:10.071  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/swagger-resources]}" onto org.springframework.http.ResponseEntity> springfox.documentation.swagger.web.ApiResourceController.swaggerResources()
2017-10-15 13:15:10.072  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/swagger-resources/configuration/ui]}" onto org.springframework.http.ResponseEntity springfox.documentation.swagger.web.ApiResourceController.uiConfiguration()
2017-10-15 13:15:10.072  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/swagger-resources/configuration/security]}" onto org.springframework.http.ResponseEntity springfox.documentation.swagger.web.ApiResourceController.securityConfiguration()
2017-10-15 13:15:10.075  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/error]}" onto public org.springframework.http.ResponseEntity> org.springframework.boot.autoconfigure.web.BasicErrorController.error(javax.servlet.http.HttpServletRequest)
2017-10-15 13:15:10.075  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/error],produces=[text/html]}" onto public org.springframework.web.servlet.ModelAndView org.springframework.boot.autoconfigure.web.BasicErrorController.errorHtml(javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse)
2017-10-15 13:15:10.315  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/env/{name:.*}],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EnvironmentMvcEndpoint.value(java.lang.String)
2017-10-15 13:15:10.315  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/env || /env.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.316  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/trace || /trace.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.319  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/loggers/{name:.*}],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.LoggersMvcEndpoint.get(java.lang.String)
2017-10-15 13:15:10.319  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/loggers/{name:.*}],methods=[POST],consumes=[application/vnd.spring-boot.actuator.v1+json || application/json],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.LoggersMvcEndpoint.set(java.lang.String,java.util.Map)
2017-10-15 13:15:10.319  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/loggers || /loggers.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.320  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/beans || /beans.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.321  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/heapdump || /heapdump.json],methods=[GET],produces=[application/octet-stream]}" onto public void org.springframework.boot.actuate.endpoint.mvc.HeapdumpMvcEndpoint.invoke(boolean,javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse) throws java.io.IOException,javax.servlet.ServletException
2017-10-15 13:15:10.322  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/auditevents || /auditevents.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public org.springframework.http.ResponseEntity org.springframework.boot.actuate.endpoint.mvc.AuditEventsMvcEndpoint.findByPrincipalAndAfterAndType(java.lang.String,java.util.Date,java.lang.String)
2017-10-15 13:15:10.323  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/info || /info.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.323  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/health || /health.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.HealthMvcEndpoint.invoke(javax.servlet.http.HttpServletRequest,java.security.Principal)
2017-10-15 13:15:10.324  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/autoconfig || /autoconfig.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.325  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/actuator || /actuator.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public org.springframework.hateoas.ResourceSupport org.springframework.boot.actuate.endpoint.mvc.HalJsonMvcEndpoint.links()
2017-10-15 13:15:10.325  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/metrics/{name:.*}],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.MetricsMvcEndpoint.value(java.lang.String)
2017-10-15 13:15:10.325  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/metrics || /metrics.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.326  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/mappings || /mappings.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.326  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/dump || /dump.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.327  INFO 2200 --- [           main] o.s.b.a.e.mvc.EndpointHandlerMapping     : Mapped "{[/configprops || /configprops.json],methods=[GET],produces=[application/vnd.spring-boot.actuator.v1+json || application/json]}" onto public java.lang.Object org.springframework.boot.actuate.endpoint.mvc.EndpointMvcAdapter.invoke()
2017-10-15 13:15:10.667  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerAdapter : Looking for @ControllerAdvice: org.springframework.boot.context.embedded.AnnotationConfigEmbeddedWebApplicationContext@1e67a849: startup date [Sun Oct 15 13:15:04 IST 2017]; root of context hierarchy
2017-10-15 13:15:10.680  INFO 2200 --- [           main] s.w.s.m.m.a.RequestMappingHandlerAdapter : Detected ResponseBodyAdvice bean in org.springframework.boot.actuate.autoconfigure.EndpointWebMvcHypermediaManagementContextConfiguration$ActuatorEndpointLinksAdvice
2017-10-15 13:15:10.751  INFO 2200 --- [           main] o.s.w.s.handler.SimpleUrlHandlerMapping  : Mapped URL path [/webjars/**] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
2017-10-15 13:15:10.752  INFO 2200 --- [           main] o.s.w.s.handler.SimpleUrlHandlerMapping  : Mapped URL path [/**] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
2017-10-15 13:15:10.777  INFO 2200 --- [           main] .m.m.a.ExceptionHandlerExceptionResolver : Detected ResponseBodyAdvice implementation in org.springframework.boot.actuate.autoconfigure.EndpointWebMvcHypermediaManagementContextConfiguration$ActuatorEndpointLinksAdvice
2017-10-15 13:15:10.797  INFO 2200 --- [           main] o.s.w.s.handler.SimpleUrlHandlerMapping  : Mapped URL path [/**/favicon.ico] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
2017-10-15 13:15:11.147  INFO 2200 --- [           main] o.s.j.e.a.AnnotationMBeanExporter        : Registering beans for JMX exposure on startup
2017-10-15 13:15:11.160  INFO 2200 --- [           main] o.s.c.support.DefaultLifecycleProcessor  : Starting beans in phase 0
2017-10-15 13:15:11.226  INFO 2200 --- [           main] o.s.c.support.DefaultLifecycleProcessor  : Starting beans in phase 2147483647
2017-10-15 13:15:11.226  INFO 2200 --- [           main] d.s.w.p.DocumentationPluginsBootstrapper : Context refreshed
2017-10-15 13:15:11.249  INFO 2200 --- [           main] d.s.w.p.DocumentationPluginsBootstrapper : Found 1 custom documentation plugin(s)
2017-10-15 13:15:11.265  INFO 2200 --- [           main] s.d.s.w.s.ApiListingReferenceScanner     : Scanning for api listing references
2017-10-15 13:15:11.473  INFO 2200 --- [           main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http)
2017-10-15 13:15:11.479  INFO 2200 --- [           main] com.eai.integration.CustomerApplication  : Started CustomerApplication in 6.972 seconds (JVM running for 10.039)

On pointing our browser to http://localhost:8080/swagger-ui.html, we will see the generated documentation rendered by Swagger UI, like this:

Expand any of these operations and test now our application. I have tested GET operation, we an see response as shown below.

On pointing our browser to http://localhost:8080/v2/api-docs, we will see the generated JSON or YAML format.

Save this file as api-docs.yaml, now we can log into Swagger editor online version import yaml file. So that we can edit documentation if necessary. Swagger Editor will look like below.

Conclusion

Besides REST API documentation and presentation with Swagger Core and Swagger UI, Swagger 2 has a whole lot of other uses beyond the scope of this post. One of my favorites is Swagger Editor, a tool to design new APIs or edit existing ones. The editor visually renders your Swagger definition and provides real-time error-feedback. Another one is Swagger Code-gen, a code generation framework for building Client SDKs, servers, and documentation from Swagger definitions. Swagger 2 also supports Swagger definition through JSON and YAML files.

Download

S. No	File Name	Size	Download
1	Integrate RESTful Web Service with Swagger.pdf	1.3 MB	Download
2	Integration-API-Customer+Swagger.zip	15 KB	Download