Streamlining Swagger Doc Creation and Distribution in Spring-Boot with Automation

Wiki Definition

Swagger is a suite of tools for API developers from SmartBear Software and a former specification upon which the OpenAPI Specification is based.

Objective

Generate Swagger documentation and publish the swagger specification in Organization’s Central Swagger Portal

Implementation

As per objective the implementation in broken in two sub objectives.

1. Generating Swagger Specification as per OpenAPI standards

2. Publishing Swagger documentation in Organization’s SwaggerHub Portal

Generating Swagger Specification

For Generating Swagger we use maven plugin ie. springdoc-openapi-maven-plugin More documentation can be found here: https://github.com/springdoc/springdoc-openapi-maven-plugin

Configuration:
            <plugin>
                <groupId>org.springdoc</groupId>
                <artifactId>springdoc-openapi-maven-plugin</artifactId>
                <version>1.4</version>
                <executions>
                    <execution>
                        <phase>install</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <skip>${skip.swagger.generate}</skip>
                    <apiDocsUrl>https://openapi_spec_source/v1/api-docs</apiDocsUrl>
                    <outputFileName>openapi.json</outputFileName>
                    <outputDir>generated/swagger-ui</outputDir>
                    <headers>
                        <Authorization>Bearer ${authToken}</Authorization>
                    </headers>
                </configuration>
            </plugin>

It is possible to customise the following plugin properties:>

• attachArtifact: install / deploy the api doc to the repository

• apiDocsUrl: The local url of your (json or yaml).

• outputDir: The output directory, where to generate the OpenAPI description.

• outputFileName: The file name that contains the OpenAPI description.

• skip: Skip execution if set to true.

• headers: List of headers to send in request

As in configuration we have put the phase install, ie. it will execute generate goal when maven install phase is executed. This will generate a API Specification based on above defined parameters. ie. it will generate the docs from instance already up and running. It will write the specification in a file named openapi.json and place this file in output directory generated/swagger-ui.

IMPORTANT

In My case All the in-coming request to my application is filtered by Azure authentication. If the request doesn’t have valid token, it will give 401 and this plugin will not be able to generate the specification. To address this we set the header as shown below:

<headers>
     <Authorization>Bearer ${authToken}</Authorization>
</headers>

Publishing Swagger Specification

To achieve this task we have used swaggerhub-maven-plugin. More documentation can be found here : https://github.com/swagger-api/swaggerhub-maven-plugin

Configuration:
        <plugin>
            <groupId>io.swagger</groupId>
            <artifactId>swaggerhub-maven-plugin</artifactId>
            <version>1.0.9</version>
            <executions>
                <execution>
                    <phase>install</phase>
                    <goals>
                        <goal>upload</goal>
                    </goals>
                    <configuration>
                        <host>swaggerhub.host.com</host>
                        <basepath>v1</basepath>
                        <api>api_defined_in_portal</api>
                        <owner>owner_defined_in_portal</owner>
                        <version>version_of_openapi_spec</version>
                        <inputFile>generated/swagger-ui/openapi.json</inputFile>
                        <token>${swaggerApiKey}</token>
                        <uploadType>inputFile</uploadType>
                    </configuration>
                </execution>
            </executions>
        </plugin>

To get this working we need following values:

• host

• basepath

[!NOTE] Dont confuse it with base path of your API.

• api

• owner

• version

• inputFile

• token

Note: This API Key should be of the owner of this organization.

IMPORTANT

While uploading the specification you will get an error:

Error when attempting to save API XXXX. Error message PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

To resolve this issue just exported the certificate from Organization’s Swagger hub portal. and imported it into CACERTS via keytool in windows.Following is the command

keytool -import -keystore cacerts -alias <Alias_Name> -file <certificate file location>