[JAVA] Changez le niveau de déploiement des documents API avec le plugin Gradle Swagger Generator

Apprenez à modifier le niveau de déploiement initial lors de la génération de la documentation de l'API à l'aide du Gradle Swagger Generator Plugin.

supposition

Ici, au lieu de générer le document API à partir du code source comme SpringFox, le document API au format Swagger UI est généré à partir du document Swagger au format YAML manuscrit. Je suppose un cas à générer.

Les versions de logiciel dont le fonctionnement a été confirmé sont les suivantes.

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

Avant la personnalisation

En supposant que la documentation de l'API se trouve dans doc / api.yaml, les paramètres de génération de l'interface utilisateur Swagger devraient ressembler à peu près à ceci:

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

Si vous générez un document API au format Swagger UI et que vous le vérifiez dans votre navigateur, vous verrez que tous les points de terminaison sont entièrement développés. C'est bien au début, mais à mesure que le nombre d'API augmente, il devient difficile de saisir l'ensemble.

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

Après personnalisation

Par conséquent, personnalisez les paramètres en fonction du Document officiel. Le fait est qu'il ne peut pas être personnalisé en tant que paramètre de plug-in, mais un fichier HTML Swagger UI personnalisé est préparé et incorporé dans le plug-in.

1. Obtenez index.html sur la page officielle de l'interface utilisateur de Swagger
2. Modifiez index.html afin qu'il puisse être incorporé dans le plugin Gradle Swagger Generator et personnalisez les paramètres à votre guise.

• Liste des valeurs de réglage → https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md

• Ici, le niveau d'expansion (docExpansion) est changé de 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,
  

1. Remplacez le fichier index.html par défaut par votre index.html personnalisé

   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
   +                }
   +            }
   +        }
        }
    }
   

Si vous générez à nouveau le document d'API au format Swagger UI et que vous le vérifiez dans le navigateur, vous pouvez voir que la liste des points de terminaison d'API est désormais affichée uniquement au niveau de l'en-tête (balise).

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

Je pense que non seulement la modification du niveau de déploiement, mais également d'autres personnalisations peuvent être réalisées par la même procédure.