The traditional approach of API documentation is either by writing service specification documents or using static service registries. With a large number of microservices, it would be hard to keep the documentation of APIs in sync.

Microservices can be documented in many ways. This section will explore how microservices can be documented using the popular Swagger framework. The following example will use Springfox libraries to generate REST API documentation. Springfox is a set of Java- and Spring-friendly libraries.

Create a new Spring Starter Project and select Web in the library selection window. Name the project chapter2.swagger.

As Springfox libraries are not part of the Spring suite, edit pom.xml and add Springfox Swagger library dependencies. Add the following dependencies to the project:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.3.1</version>
</dependency>  
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.3.1</version>
</dependency>

Create a REST service similar to the services created earlier, but also add the @EnableSwagger2 annotation, as follows:

@SpringBootApplication
@EnableSwagger2
public class Application {

This is all that's required for a basic Swagger documentation. Start the application and point the browser to http://localhost:8080/swagger-ui.html. This will open the Swagger API documentation page:

As shown in the diagram, the Swagger lists out the possible operations on Greet Controller. Click on the GET operation. This expands the GET row, which provides an option to try out the operation.