Building Microservice with Spring Boot — Part 04

Swagger2 API Documentation For Microservices.

Swagger is one of the best automated tools that was developed mainly for the use of generating API documentation and also could be used as a free service to test API, to generate server stubs, to design API and many more. Swagger API documentation comes as a JSON and Swagger UI which is also another product of swagger will consume the same JSON and generate fancy and user-friendly UI to read the API documentation and test the API.

How to configure Swagger for a Microservices Project?

For this scenario, We’ve to configure swagger core on all the microservices which we are generating API documentation. Then configure Swagger and Swagger UI on an API gateway and finally config API gateway to capture swagger JSON from all other microservices.

Swagger Implementation with Microservices.

How to configure Swagger with SpringBoot?

Swagger implementation with SpringBoot is quite an easy task as it was already discussed in my previous blog post.

How to configure API Gateway (Zuul) to consume swagger documentation from all microservices?

First, we need to add the same dependencies which were used for SpringBoot swagger implementation with API gateway.

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

Then, here comes the configuration part. Here we’re overriding the default implementation of swagger which comes with @EnableSwagger2 annotation by a Primary annotation to our custom Documentation Configurations.

Inside the overridden configuration, we can introduce all the swagger JSON endpoints as below,

resources.add(swaggerResource("user-service", "/user/v2/api-docs", "2.0"));
resources.add(swaggerResource("news-service", "/news/v2/api-docs", "2.0"));

Full code Snippet,

package com.clabz.medium.config;

import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;

import java.util.ArrayList;
import java.util.List;

import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

/**
* Project Name : medium-api-gateway
* Author : ChinthakaDi
* Date : 11/4/2018 - 3:23 AM
*/
@Component
@Primary //Override Original swagger implementation with custom swagger resource provider.
public class DocumentationConfig implements SwaggerResourcesProvider {

@Override
public List get() {
List resources = new ArrayList();
resources.add(swaggerResource("user-service", "/user/v2/api-docs", "2.0"));
resources.add(swaggerResource("news-service", "/news/v2/api-docs", "2.0"));
return resources;
}

private SwaggerResource swaggerResource(String name, String location, String version) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion(version);
return swaggerResource;
}

}

That’s it, Swagger and Zuul API Gateway will take care of the rest. Just start your whole microservices base. Then access /swagger-ui.html with adding the host address of your API gateway.

http://localhost:3000/swagger-ui.html
Swagger-UI generated for the microservices project.

Happy Coding.

Next in this series: — Building Microservices with Spring Boot — Part 05

Deploying microservices using docker-compose on docker swarm.