[How-to] Spring boot Swagger 3 integration

In this page, we’ll integrate Swagger with an existing Spring Boot project.

So let’s get started. For those who are new to Swagger, I have provided below introduction text below. You can skip straight to the point – step by step on how to integrate Swagger 3 with Spring boot.

Skip Intro – Swagger 3

We use Swagger to specify documentation for use with development or integration with other software systems. Swagger specifies the format of the REST web services including URL, Resources, methods, etc. Swagger will generate documentation from the application code and handle the rendering part as well.

Contents

• Prepare dependency
• Adding Swagger annotation to Spring boot REST controller
• Adding Docket
• Adding ApiInfo
• Swagger Controller Documentation
• Swagger POJO level Documentation

Skip YouTube video [Good for eyes]

Prepare dependency

We need to add two dependencies to get started. Springfox and its UI. Here we go:

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>

About Springfox:
The Springfox suite of java libraries are all about automating the generation of machine and human readable specifications for JSON APIs. Read more about this here. – http://springfox.github.io/springfox/docs/current/

Adding Swagger annotation to Spring boot REST controller

@EnableSwagger2 annotation enables Springfox Swagger. We need to document API which we are going to expose through our REST endpoint in our spring boot application. This is done by grouping them with a terminology called docket.

Adding Docket

A docket groups APIs here. The grouping is done based on name etc. Let’s now create a Spring Java configuration class to boot up and make Springfox running.

package com.cloudiknow;

import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class ApplicationConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()                .apis(RequestHandlerSelectors.basePackage("com.cloudiknow.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }
}

Adding ApiInfo

The ApiInfo class contains custom information about the API. This helps us in setting up license information to our Spring boot project.

@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cloudiknow.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo getApiInfo() {
        Contact contact = new Contact("CloudiKnow Cloud Academy", "https://cloudiknow.com", "[email protected]");
        return new ApiInfoBuilder()
                .title("Example Title - CloudiKnow")
                .description("Example API")
                .version("1.0.1")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }

Controller and POJO Level Documentation

Annotation	Explanation
@Api	This annotation is used to explain each rest controller class.
@ApiOperation	This annotation is used to explain to describe the resources and methods.
@ApiResponse	This annotation is used to explain to describe other responses that can be returned by the operation.
@ApiModelProperty	This annotation to describe the properties of the POJO(Bean) class.