Gradle Swagger Generator PluginでAPI文書の展開レベルを変更する

Gradle Swagger Generator Plugin を使ってAPIドキュメントを生成する場合に、初期状態の展開レベルを変更する方法を紹介します。

前提

ここでは、 SpringFox のようにソースコードからAPIドキュメントを生成するケースではなく、手書きしたYAML形式のSwaggerドキュメントからSwagger UI形式のAPIドキュメントを生成するケースを想定しています。

動作確認したソフトウェアのバージョンは次の通りです。

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

カスタマイズ前

doc/api.yaml にAPIドキュメントがあるとして、Swagger UIを生成するための設定はおおむね次のようになっているはずです。

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')
    }
}

Swagger UI形式のAPIドキュメントを生成してブラウザで確認すると、すべてのエンドポイントが完全に展開された状態になることが分かります。最初のうちはこれでも問題ありませんが、APIの数が増えてくると全体が把握しづらくなります。

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

カスタマイズ後

そこで、 公式ドキュメント に従って設定をカスタマイズします。プラグインの設定としてカスタマイズできるわけではなく、カスタマイズ済みのSwagger UIのHTMLファイルを用意してプラグインに組み込むという点がポイントです。

1. Swagger UI 公式ページから index.html を取得する

2. Gradle Swagger Generator Plugin に組み込めるようindex.htmlを修正し、設定値をお好みでカスタマイズする

   • 設定値の一覧 → https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md
   • ここでは、展開レベル (docExpansion) を full → 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,
   

3. カスタマイズしたindex.htmlでデフォルトの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
   +                }
   +            }
   +        }
        }
    }
   

再度、Swagger UI形式のAPIドキュメントを生成してブラウザで確認すると、今度はAPIエンドポイントの一覧が見出し（タグ）レベルだけで表示されるようになっていることが分かります。

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

展開レベルの変更だけに限らず、ほかのカスタマイズも同様の手順で実現できると思います。