[JAVA] 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.

• Oracle JDK 1.8
• Gradle 4.10
• Gradle Swagger Generator Plugin 2.16.0

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

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.

• List of setting values → https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md

• Here, the expansion level (docExpansion) is changed from full to list.

  diff --git a/doc/index.html b/doc/index.html
  index 549f5f3..163140a 100644
  --- a/doc/index.html
  +++ b/doc/index.html
  @@ -40,6 +40,10 @@
       window.onload = function() {
         // Begin Swagger UI call region
         const ui = SwaggerUIBundle({
  +        spec: window.swaggerSpec,   // (mandatory) use source of swagger-spec.js
  +        validatorUrl: null,         // (mandatory) disable validator
  +        docExpansion: 'list',       // expand only the tags
  +
           url: "https://petstore.swagger.io/v2/swagger.json",
           dom_id: '#swagger-ui',
           deepLinking: true,
  

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

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