Change the deployment level of API documents with Gradle Swagger Generator Plugin

I will show you how to change the initial deployment level when generating API documents using Gradle Swagger Generator Plugin.

Premise

Here, instead of generating the API document from the source code like SpringFox, the Swagger UI format API document is generated from the handwritten YAML format Swagger document. I'm assuming a case to generate.

The software versions that have been confirmed to work are as follows.

Before customization

Assuming you have the API documentation in doc / api.yaml, the settings for generating the Swagger UI should look roughly like this:

plugins {
    id 'org.hidetake.swagger.generator' version '2.16.0'
}

dependencies {
    swaggerUI 'org.webjars:swagger-ui:3.20.3'
}

swaggerSources {
    api {
        inputFile = file('doc/api.yaml')
    }
}

If you generate an API document in Swagger UI format and check it in your browser, you will see that all the endpoints are fully deployed. This is fine at first, but as the number of APIs increases, it becomes harder to understand the whole thing.

$ ./gradlew generateSwaggerUI
$ open build/swagger-ui-api/index.html

image.png

After customization

Therefore, customize the settings according to the Official Documentation. The point is that it cannot be customized as a plugin setting, but a customized Swagger UI HTML file is prepared and incorporated into the plugin.

  1. Get index.html from the Swagger UI official page
  2. Modify index.html so that it can be incorporated into the Gradle Swagger Generator Plugin, and customize the settings to your liking.
  1. Override the default index.html with your customized index.html

    diff --git a/build.gradle b/build.gradle
    index 0aadabc..286e95b 100644
    --- a/build.gradle
    +++ b/build.gradle
    @@ -49,5 +49,13 @@ jacocoTestReport {
     swaggerSources {
         api {
             inputFile = file('doc/api.yaml')
    +        ui {
    +            doLast {
    +                copy {
    +                    from 'doc/index.html'
    +                    into outputDir
    +                }
    +            }
    +        }
         }
     }
    

If you generate the Swagger UI format API document again and check it in the browser, you can see that the list of API endpoints is now displayed only at the heading (tag) level.

$ ./gradlew generateSwaggerUI
$ open build/swagger-ui-api/index.html

image.png

I think that not only changing the deployment level but also other customizations can be realized by the same procedure.

Recommended Posts

Change the deployment level of API documents with Gradle Swagger Generator Plugin
Change the port with SpringBoot
A story about hitting the League Of Legends API with JAVA