[JAVA] Ändern Sie die Bereitstellungsstufe von API-Dokumenten mit dem Gradle Swagger Generator Plugin

Erfahren Sie, wie Sie die anfängliche Bereitstellungsstufe beim Generieren der API-Dokumentation mithilfe des Gradle Swagger Generator-Plugins (https://github.com/int128/gradle-swagger-generator-plugin) ändern.

Annahme

Anstatt das API-Dokument aus dem Quellcode wie SpringFox zu generieren, wird hier das API-Dokument im Swagger-UI-Format aus dem handgeschriebenen Swagger-Dokument im YAML-Format generiert. Ich gehe davon aus, dass ein Fall generiert werden muss.

Die Softwareversionen, deren Funktion bestätigt wurde, lauten wie folgt.

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

Vor der Anpassung

Angenommen, die API-Dokumentation befindet sich in "doc / api.yaml", sollten die Einstellungen zum Generieren der Swagger-Benutzeroberfläche ungefähr so aussehen:

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

Wenn Sie ein API-Dokument im Swagger-UI-Format generieren und in Ihrem Browser überprüfen, werden Sie feststellen, dass alle Endpunkte vollständig erweitert sind. Dies ist zunächst in Ordnung, aber mit zunehmender Anzahl von APIs wird es schwierig, das Ganze zu erfassen.

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

Nach der Anpassung

Passen Sie daher die Einstellungen gemäß dem [offiziellen Dokument] an (https://github.com/int128/gradle-swagger-generator-plugin#configure-swagger-ui). Der Punkt ist, dass es nicht als Plug-In-Einstellung angepasst werden kann, sondern eine angepasste HTML-Datei für die Swagger-Benutzeroberfläche vorbereitet und in das Plug-In integriert wird.

1. Holen Sie sich index.html von der offiziellen Swagger-UI-Seite
2. Ändern Sie index.html so, dass es in das Gradle Swagger Generator Plugin integriert werden kann, und passen Sie die Einstellungen nach Ihren Wünschen an.

• Liste der Einstellwerte → https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md

• Hier wird die Erweiterungsstufe (docExpansion) von full in list geändert.

  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. Überschreiben Sie die Standard-index.html mit Ihrer benutzerdefinierten 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
   +                }
   +            }
   +        }
        }
    }
   

Wenn Sie das API-Dokument im Swagger-UI-Format erneut generieren und im Browser überprüfen, wird angezeigt, dass die Liste der API-Endpunkte jetzt nur auf Überschriftenebene (Tag) angezeigt wird.

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

Ich denke, dass nicht nur das Ändern der Bereitstellungsebene, sondern auch andere Anpassungen durch dasselbe Verfahren realisiert werden können.