Implementation of swagger in SpringBoot API

We have created SpringBoot API in our previous post and you can download.

We could have lot of API's and if people don't know how to use it than it rather useless.There are a few tools which can help us document our API. We can use Swagger, Apiary or RAML. For spring-boot, there is a set of libraries which can help document our API in a very easy manner using Swagger.

Swagger:

Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation.

For more information you can go to their official website.

In previous post we exposed 4 REST endpoints which is:

get all employees names: GET /api/employee
get a specific employee: GET /api/employee/{id}
add an employee: POST /api/employee
delete an employee: DELETE /api/employee/{id}

Now, we will do swagger documentation for these API's.

We have already these files:

pom.xml
EmployeesApplication.java
Employee.java
EmployeeRepository.java
EmployeesDataController.java
application.properties
data.sql

In addition, we will add these files:

BasicAuthenticationPoint.java
SecurityConfiguration.java
SwaggerConfig.java

Implementation of swagger in SpringBoot API

pom.xml: we have to do is add 2 dependencies into our POM to enable Swagger2.

<!--springfox dependency -->
        <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>

SwaggerConfig.java: we will create a bean which creates a Docket. This is the starting point of the configuration for your Swagger documentation.

package com.engineeernitesh.employeesapi.swagger;

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket employeeApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(regex("/api/employee.*"))
                .build()
                .apiInfo(metaData());
    }

    private ApiInfo metaData() {
        ApiInfo apiInfo = new ApiInfo(
                "Employee API",
                "This is test",
                "1.0",
                "Terms of service",
                new Contact("", "", "nitesh04singh@gmail.com"),
                "Apache License Version 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>()
        );
        return apiInfo;
    }


}

@EnableSwagger2 annotation is used to enable the Swagger2 for our Spring Boot application.

By setting the basePackage to the right location, it will look for RestController classes and generate documentation items based on annotations.

Using ApiInfo we can add some basic information of the API.

EmployeesDataController: We can add @ApiOperation annotation to set a description of the operation and what kind of response you expect.

@ApiOperation(value = "View a list of employees", response = Iterable.class)
    List<Employee> getEmployees() {}

Now, start the application and go to http://localhost:8080/swagger-ui.html. You will be able to see all API's definition and now you can use these API's.

References:

Nitesh Kumar's Technical Blog

Monday, 14 January 2019