Spring boot with Swagger2 API documentation(Part4)

Swagger 2 is an open-source project to provide the functionality of exposing the REST API endpoint to consumers and developers. It provides the information through HTTP protocols and It has web-based UI, where developers or consumers can get the information or metadata of RESTful API. It also provides the functionality to interact with the RESTful API. In this article, I will integrate the Springfox swagger2 package to implement the Swagger 2 API documentation in the spring boot application.

Prerequisites
1. Git Installed in your pc
2. IntelliJ IDEA Community Edition
3. Java Installed in your PC (8 to 11) any version
5. Json Viewer Plugins for Chrome Browser (https://github.com/tulios/json-viewer)
6. Docker and Docker Compose

I already have a repository with spring boot in GitHub you can clone it first

> git clone https://github.com/tariqulislam/spring-boot-docker.git

Project Structure of spring-boot-docker in IntelliJ Idea

To Run the Project In Local environment

If you have MySQL Server in the local environment or PC, And Want to run the project with Local Env, change the data source URL to localhost and change the dialect as a locally installed MySQL server in application.properties file.

Configure the local MySQL Server with Spring boot

Configuring the Run/Debug Configuration

To Locally Stop And Start the Program In Intellij Idea(Figure 1)

To Run the project in Docker environment

The project is already configured with a docker environment you can see the configuration at docker-compose.yml file which contains two services mysql-service and web-service.

To connect with MySQL Service from Docker Environment to spring boot application, you need to change some configuration at application.properties

To Rebuild the Docker application with following below command

> docker-compose up --build

Configure the Spring Boot Application with Springfox Swagger2

Open the Terminal or open the new tab of the terminal, If you are familiar with git, then create the new branch by following below command.

> git checkout -b feature/swagger_integration

Add the swagger spring dependency to pom.xml file

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

Enable the Swagger Documentation to Spring Boot

Add the @EnableSwagger2 annotation calss to the main class of the application inStarterApplication.java file

package com.example.starter;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class StarterApplication {

   public static void main(String[] args) {
      SpringApplication.run(StarterApplication.class, args);
   }

}

Using Docker, you should use those following command

Step 1

# First Stop the services by following command
> docker-compose down

Step2

# Then rebuild the project by following command
> docker-compose up --build

To run in Program in IntelliJ Idea you have to follow the (Figure 1)

Open the postman and check the swagger is installed successfully to Spring Boot Application

http://localhost:4000/v2/api-docs

After that, you can see the following output in the Browser if swagger2 installed with Spring boot Perfectly.

It is a JSON version of the swagger tools

Install the Springfox Swagger2 UI to show the API endpoint with Presentational View

To install the Swagger2 UI, need to install another spring boot dependency named springfox-swagger-ui

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Down the docker service and run it again and go to browse with the following links. Or Local Env, you need to restart the spring boot application from Intellij Idea Tool bar

http://localhost:4000/swagger-ui.html

Now you see the UI version of the Swagger API Documentation Endpoint

You see that there are extra spring core related controller API added to the swagger endpoint, for production security purpose we need to remove those API URL from swagger ui endpoint, so you need to configure the swagger so the system controller endpoint does not show in the swagger UI endpoint URL.

About Docket

There is a special Object named Docket by this, we can override the configurations related to Swagger in the spring boot project.

You need to create theBean for configuring the Swagger with Docket object to StarterApplication.java file.

Then restart the docker service again and build it. And now see in the browser all the unnecessary endpoint is gone

The unnecessary API endpoint is removing from the Swagger UI endpoint

About ApiInfo for Swagger Documentation

To customize the Title, Description, Service URL and other configuration of the Swagger UI endpoint, Springfox Swagger2 provide the Object named ApiInfo to configure it.

In application, you have to customize the UI for the project so you can add the following code below, the function related to swagger UI

Line 3: Take the title of the Swagger UI Endpoint
Line 4: Take the Description of the Endpoint
Line 5: Version number of documentaion
Line 6: Terms and Service Information for documentaiton
Line 7: Contact Address for admin using springfox Contact Object
Line 10: Licence Name
Line 11: Licence Url

Then add `apidetails()`as apiInfo() object to Docket Bean named swaggerConfiguration

@Bean
public Docket swaggerConfiguration() {
   return new Docket(DocumentationType.SWAGGER_2)
         .select()
         .paths(PathSelectors.ant("/api/v1/**"))
     .apis(RequestHandlerSelectors.basePackage("com.example.starter"))
         .build()
         .apiInfo(apiDetails());
}

Restart and run locally or Rebuild the program with Docker Compose again,

For Docker Command

> docker-compose up --build

To Rebuild with IntelliJ Idea goto tool bar and click on that button for restart the project

Then go to Browser with that Url

http://localhost:4000/swagger-ui.html

Add the Edition Documentation to API Endpoint

If you want to add the additional documentation to a specific method or function

First, go to Controller where the method is created for documenting the controller methods add the @ApiOperation annotation class to that method

@ApiOperation(value = "Show All Members",
            notes = "This will provide the the member information",
            response = Member.class)
public List<Member> all() {
    return memberService.getAllMembers();
}

If we want to add the Method argument level documentation we can add this

@PutMapping("/members/{id}")
public ResponseEntity<Member> updateMember(
   @Valid @RequestBody Member member,
   @ApiParam("Pass the Member id Find the Member Existing Info")
   @PathVariable(value= "id") Long id) {
    return ResponseEntity.ok(memberService.updateMember(member, id));
}

If you want to add the documentation details to Model class you have to use @ApiModel annotation class in Model object.

@ApiModel(description = "This is Member Model")
public class Member {}

To documenting the property of the API you can use @ApiModelProperty Annotation class.

@ApiModelProperty(dataType = "Integer" , example = "123")
private Long id;

API Interaction with Swagger UI

Call The GET API all data API server

POST Method Interaction with Swagger UI

PUT API Interacted with Swagger UI

DELETE Interacted with Swagger API

You can find the whole source code at feature/swagger-integration, branch of the below project

tariqulislam/spring-boot-docker