Swagger is an auto-documentation-generation tool. It is simple to use.

To start with, we need to add maven dependencies, as follows:

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>

And next, we will add the configuration:

package com.packt.Microservices.calculator;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
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;

/**** This is main configuration class for spring boot application.*/
@Configuration
@SpringBootApplication
@EnableSwagger2
public class CalculatorApplication 
{
 /**** Swagger configuration**/

 @return
 @Bean
 public Docket SwaggerDocumentationApi() 
 {
   return new  Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.packt.Microservices.calculator")).paths(reg ex("/.*")).build().apiInfo(metaData());
 }

 private ApiInfo metaData() 
 {
  ApiInfo apiInfo = new ApiInfo("Microservices Example REST  API","Spring Boot based REST API for Calculator","1.0","Terms of service- NA",new Contact("Packt Team", "https://packt.com", "[email protected]"),"Apache License Version 2.0","https://www.apache.org/licenses/LICENSE-2.0");

  return apiInfo;
 }

 /**** Main method to initialize spring boot application.* @param  args*/
 public static void main(String[] args) 
 {
  SpringApplication.run(CalculatorApplication.class, args);
 }
}

You can see that all we have done is added a configuration for Swagger, and no code changes are done.

After the application is deployed locally, if we open the Swagger link, http://localhost:8080/swagger-ui.html#/, we can see the documentation shown by Swagger. The following image shows a sample documentation:

Swagger gets us to the next level; that is, click on any service and Swagger will give you more details about the service. For example, if we click on add service, we get to see something like the following on screen:

When you click on a particular service, Swagger gives us complete details about the service. In addition, to just view the details, you can also try out the service in the Swagger interface itself. The image below shows how to use the service:

So far, we have looked at the default documentation provided by Swagger, but it also gives us additional options where we can add more details to our documentation. Let's take a look at a few available options.

You can use the @Api and @Apioperations annotations, as shown in the following code, to add information at the API class and operation levels, respectively:

@Api(value="SimpleCalculator", description="Manages basic calculator operation on two numbers")
@RestController
public class CalculatorController 
{

  @ApiOperation(value = "Add given two numbers", response = Integer.class)
  @GetMapping("/add")
  public int addNumber(int num1, int num2) 
  {
    return(num1+num2);
  }

  @ApiOperation(value = "Subract second number from first", response = Integer.class)
  @GetMapping("/subtract")
  public int subtractNumber(int num1, int num2) 
  {
    return(num1-num2);
  }

  @ApiOperation(value = "Multiply two numbers", response = Integer.class)
  @GetMapping("/multiply")
  public int multiplyNumber(int num1, int num2)
  {
    return(num1*num2);
  }

  @ApiOperation(value = "Number one divided by second number",  response = Float.class)
  @GetMapping("/divide")
  public float divideNumber(float num1, float num2) 
  {
    return(float)(num1/num2);
  }
 }

This will add additional information to the documentation, as shown here: 

Additionally, we can provide more information related to the service response, as shown in the following code:

@ApiResponses(value = {
@ApiResponse(code = 200, message = "Successfully Added two numbers."),
@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")
})

Most of the time, the default Swagger documentation will suffice, but as mentioned above, we can enhance the documentation by adding more details through annotations.

While we are talking about annotations, there is another simple way to document your APIs – through a tool called APIdoc, which provides us simple annotations that can help us with to document our Microservice APIs. Let's take a look at this in the next section.