API specifications/documentation is a key element for cross-team communication. In Java tech stack, we always use Swagger to generate API specifications and use Swagger UI to visualize the specification. But there is an issue in microservices architecture when using Swagger. This post will discuss the problem in Microservices API Documentation.

The problem in Microservices API Documentation

As we all know, it is very easy to use springdoc-openapi to generate Swagger API Documentation for your backend services. But if you are using Swagger for microservices API documentation, you probably got this problem.

The problem with the above diagram is that each microservice contains a Swagger Documentation endpoint which means your team needs to access multiple endpoints to view different Swagger Documentation. That said, your team needs to remember different URLs for different Swagger API Documentation. Also, it is hard to manage access to API specifications. Let’s say, there are A, B, C, and D four API specifications, and Ray is only allowed to access A, B, and C. Under this context, it is difficult for us to manage Swagger access.

How do we solve this problem?

To solve this problem, we can leverage SwaggerHub to host all the API specifications instead of using Swagger UI to visualize single API documentation.

Now, we form another workflow to centralize and synchronize our API specifications to SwaggerHub.

1. Developer commit code to Git repository

2. Run CI pipeline to generate documentation and upload the documentation to SwaggerHub

3. The team can login to SwaggerHub and view the API specifications that they are allowed to access

To set up this workflow for a Java Stack, we need two Gradle plugins:

1. Swagger Gradle Plugin

2. Springdoc OpenApi Gradle Plugin

Now, we need to add some configurations to the Gradle:

Step 1: Add plugins

plugins {

    id "com.github.johnrengelman.processes" version "0.5.0"

    id "org.springdoc.openapi-gradle-plugin" version "1.3.3"

    id "io.swagger.swaggerhub" version "1.0.1"

}

Step 2: Add custom Gradle tasks

openApi {

    apiDocsUrl.set("http://localhost:9000/v3/api-docs.yaml")

    outputDir.set(file("$buildDir/docs"))

    outputFileName.set("openapi.json")

    waitTimeInSeconds.set(60)

    forkProperties.set("-Dspring.profiles.active=api -Dserver.port=9000")

}

swaggerhubUpload{

    api 'api-docs'

    owner 'api'

    version '1.0.0'

    isPrivate true

    inputFile "$buildDir/docs/openapi.json"

    token YOUR_SWAGGER_HUB_API_KEY

}

After that, you can run openApi and swaggerhubUpload tasks in your CI pipeline. It will upload the API specifications to your SwaggerHub directly.

Now, your team can view the documentation via SwaggerHub directly. Also, the SwaggerHub admin can manage the user access rights through the SwaggerHub portal.