Documentation is often a neglected topic in the software world. In a hurry to deliver the end product to the user or get the applications deployed, we tend to ignore the importance of documentation, as it is not something that the end user will directly view. But as the application grows, we start feeling the pain of missing documentation. Imagine you are given a code without any documentation: it will take you more time to go through the code and understand it. Whereas if code, classes, and methods are properly documented, it becomes much easier to understand the code. If you already have experience with Java, you've probably used JavaDocs, which is a very strong and easy way to document code.

We will not get into the details of JavaDocs here, instead we'll focus more on the Microservices documentation, and particularly on API-level documentation, which is important, as often the users of these APIs are not the same developers who have implemented the APIs. These will be used by frontend developers or other teams using your API, so we need ways in which we can convey how to use a Microservice API properly to the teams and fellow developers.

Let's start with a simple calculator Microservice. Say we are exposing four basic operations: add, subtract, multiply, and divide, as follows:

package com.packt.Microservices.calculator;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class CalculatorController 
{
@GetMapping("/add")
 public int addNumber(int num1, int num2) 
 {
  return(num1+num2);
 }
@GetMapping("/subtract")
public int subtractNumber(int num1, int num2) 
 {
  return(num1-num2);
 }
@GetMapping("/multiply")
public int multiplyNumber(int num1, int num2) 
 {
  return(num1*num2);
 }
 @GetMapping("/divide")
public float divideNumber(float num1, float num2) 
 {
  return(float)(num1/num2);
 }
}

This is a completely working service, but this does not tell users how to use it. How do we call a service? How many arguments will it take? Does it take decimals?

So without proper documentation, a service is not in a usable state. Anyone trying to use this service would be confused about what the service does and how to use it, so we need to make sure we provide proper documentation to fellow developers and end users.

Let's start with the easiest option, that is, Swagger.