Swagger provides some additional annotations required on top of existing Spring MVC annotations. Let's see the following example using these annotations.

In the microservice application, each REST controller that is supposed to be documented should be annotated with the @Api annotation:

@Api( value = "/customer", description = "Manage Customer" ) 
public class CustomerController { 
   // ... 
}

The CustomerController class has been annotated with the @Api annotation with the value and description attributes. The @Api annotation narrates the description about the responsibilities of the controller.

Next, each request handler methods of the Rest Controller class that is supposed to be documented should be annotated with the @ApiOperation annotation. This annotation narrates the responsibility of the specific method. You can also use another Swagger annotation, @ApiResponses/@ApiResponse, with request handler methods. Let's see the following example:

@ApiOperation(value = "Returns Customer Name") 
@ApiResponses( 
     value = { 
   @ApiResponse(code = 100, message = "100 is the message"), 
   @ApiResponse(code = 200, message = "Successful Return Customer Name") 
        } 
) 
@GetMapping("/name") 
public String customerName(@ApiParam(name="name", value="Customer Name") String name){ 
   return "Arnav Rajput"; 
} 

The request handler method of CustomerController has annotated with the @ApiOperation and @ApiResponse/@ApiResponses.

If the request handler method accepts parameters, those should be annotated with the @ApiParam annotation. As you can see in the preceding example, the @ApiOperation annotation narrates the responsibility of the specific method.

Similarly, you can also document your model classes to provide the model schema, which helps with documenting the request-response structure using the specific annotation, such as using the @ApiModel annotations. The REST resource classes or model classes require special annotations—@ApiModel and @ApiModelProperty. Let's see the following Customer model class:

@ApiModel( value = "Customer", description = "Customer resource representation" )
public class Customer {
@ApiModelProperty(notes = "Name of the Customer") String name; @ApiModelProperty(notes = "Email of the Customer") String email; @ApiModelProperty(notes = "Mobile of the Customer") String mobile; @ApiModelProperty(notes = "Address of the Customer") String address; //... }

Let's run your Spring Boot microservice project and refresh the browser:

It has rendered the details about the model of the customer class. Now, Swagger provided more descriptive API documentation. So, you can easily customize the API documentation using Swagger annotations.

Swagger enables the REST API service producer to update the API documentation in real time. The client and API documentation system are creating at the same pace as the server. Swagger is maintaining the synchronization in APIs and its documentation with the methods, parameters, and models described in the server code.