Centralized Swagger/OpenAPI UI for all the different microservices on a single swagger URL i.e accessing all the URLs through one

Question

I have around 16 microservices built in Spring Boot that communicate with each other and each microservice is having multiple APIs in it. I have configured OpenAPI for each of the microservices. So it gives me 16 "swagger-ui" URLs. I wonder how can I centralize all Swagger URLs on one single page; I want only 1 swagger URL to access all the 16 microservices.

I have gone through the following as well but didn't get any solution Centralize Swagger at one place for All microservices

Please guide me to the best way to achieve it.

Answer 1

If all you µservices use the same host, you can create a Spring Boot µservice which acts as a openAPI gateway using spring-doc. (If they are not using the same host, you will have to deal with CORS issues)

1. First, add the following dependencies to your new gateway µservice

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. Then, add the below configuration

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    configUrl: ${server.servlet.contextPath}/v3/api-docs/swagger-config
    url: ${server.servlet.contextPath}/v3/api-docs
    urls:
      - name: api-customer
        url: /customer/v3/api-docs
      - name: api-cart
        url: /cart/v3/api-docs
      - name: api-product
        url: /product/v3/api-docs

For each µservice you have to fill in the url property with is the url to the openAPI definition at json or yaml format.

For springdoc library which uses openAPI 3.0 the default url is /${µServiceContextPath}/v3/api-docs For springfox library which uses openAPI 2.0 the default url is /${µServiceContextPath}/v2/api-docs

3. Finally access to /${contextPath}/swagger-ui.html and you will be able to select an openAPI

Answer 2

I found a working solution on GitHub. It works with Spring Cloud Discovery but can be easily adapted to other discovery solutions. The basic idea is to generate for Swagger the list of URLs pointing to the OpenAPI JSON files.

The result is similar to one in the @shadyx's answer, but the list is generated dynamically

@RestController
public class SwaggerUiConfig {

    @Autowired
    private DiscoveryClient discoveryClient;

    @GetMapping("/swagger-config.json")
    public Map<String, Object> swaggerConfig() {
        List<SwaggerUrl> urls = new LinkedList<>();
        discoveryClient.getServices().forEach(serviceName -> 
                        discoveryClient.getInstances(serviceName).forEach(serviceInstance ->
                                urls.add(new SwaggerUrl(serviceName, serviceInstance.getUri() + "/v3/api-docs"))
                        )
        );
        return Map.of("urls", urls);
    }
}

application.yaml

springdoc:
  swagger-ui:
    configUrl: "/swagger-config.json"

Sample of the generated swagger-config.json

{
  "urls": [
    {
      "url": "http://localhost:8088/v3/api-docs/users",
      "name": "users"
    },
    {
      "url": "http://localhost:8088/v3/api-docs/stores",
      "name": "stores"
    }
  ]
}