"Hé, c’est bien joli tout ça, mais dans mon équipe on a l’habitude d’utiliser Swagger, c’est bien plus complet comme outil, on peut même lancer des requêtes depuis la page de documentation !"
— Un développeur qui a ses petites habitudes
La remarque est intéressante ! En quittant Swagger, on passe d’une page interactive à une page HTML complètement statique.
On perdrait donc au change ?
Peut-être … mais ne parlons pas trop vite !
Allons droit au but : il est tout à fait possible de générer un fichier décrivant l’API dans un format "Swagger-compatible", autrement dit au format OpenAPI. Mais pas par défaut, nous devons ajouter une petite dépendance qui vient étendre les capacités de Spring REST Docs :
<dependency>
<groupId>com.epages</groupId>
<artifactId>restdocs-api-spec-mockmvc</artifactId>
<version>0.14.1</version>
<scope>test</scope>
</dependency>
Et lorsque l’on documente un endpoint, il faut désormais importer la méthode document() de cette dépendance :
import static com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper.document;
En relançant les tests, on s’aperçoit alors qu’un nouveau "snippet" est généré : resource.json.
Il s’agit d’un snippet au format OpenAPI. Il ne reste donc plus qu’à rassembler ces snippets en un seul fichier, un peu comme nous savons déjà le faire pour la version AsciiDoc. Mais cette fois-ci, nul besoin d’un "fichier racine", nous allons nous servir d’un plugin.
Mais … problème en vue ! La dépendance ajoutée ne propose qu’un plugin Gradle et notre projet utilise Maven ! Pas de panique, la communauté est vaste et prévoyante, il existe un plugin pour générer la documentation finale : restdocs-spec-maven-plugin.
En l’ajoutant dans la section "build" du fichier pom.xml, nous allons pouvoir générer un fichier au format OpenAPI en plus du fichier HTML précédent :
<plugin>
<groupId>io.github.berkleytechnologyservices</groupId>
<artifactId>restdocs-spec-maven-plugin</artifactId>
<version>0.21</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<name>Demo Spring REST Docs</name>
<version>${project.version}</version>
<host>localhost:8080</host>
<outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
<filename>openapi</filename>
<specification>OPENAPI_V3</specification>
<description>API description for Demo Spring REST Docs service</description>
</configuration>
</execution>
</executions>
</plugin>
De la même manière que pour le fichier HTML, comme ce fichier openapi.yml est déposé dans un répertoire exposé, il sera accessible une fois l’application lancée. Et à partir de ce moment-là, libre à vous de le fournir comme point d’entrée à une instance de Swagger UI.
Pour cela, on peut tester rapidement la qualité du fichier généré en démarrant une instance de Swagger UI :
docker run -p 80:8080 swaggerapi/swagger-ui
Une fois le container démarré, il suffit de se rendre sur http://localhost (Swagger UI fonctionnant sur le port 80 d’après notre commande ci-dessus), et de fournir l’adresse du fichier openapi.yml dans la barre de recherche en haut de la page. La documentation apparait … avec tout le fonctionnement habituel de Swagger. Alors, il est satisfait le développeur qui a ses petites habitudes ?
Alors, est-ce que vous commencez à être convaincu par Spring REST Docs ?
C’est en tout cas le cas pour ma part et je vais continuer de le déployer sur les projets sur lesquels j’ai le plaisir de travailler !
Les autres articles de cette série :
