Documentation d’API avec Swagger • wi-run, the code

Comme beaucoup d’autres équipes, nous avons été confrontés à la maintenance de legacy peu documenté et, force est de constater que cela coûte cher. C’est pourquoi, pour tous nos services, nous avons mis en place une javadoc et une documentation d’API REST générées à partir du code, lors du build. C’est la partie documentation REST que l’on présente ici avec un module Maven qui génère un fichier Swagger.

Le projet est disponible sur github: rocket-swagger.

Contexte

Jusqu’à maintenant, nos projets généraient une documentation OpenAPI v2 via des annotations Swagger v1.5.x. Afin de rester à jour et d’avoir la meilleure documentation possible, nous avons entrepris de migrer notre documentation vers OpenAPI v3 avec Swagger v2.x. La génération se fait via un plugin Maven fourni par Swagger, mais, dans le cas de Swagger v2.x, seule la génération à partir de code JaxRS est prise en charge nativement. Or, nos projets backend sont majoritairement à base de Spring Boot Webflux.

Heureusement, le plugin Swagger Maven pour la version OpenAPI 3 est hautement configurable et permet de brancher assez simplement une implémentation autre que celle de JaxRS fournie par défaut.

C’est de là qu’est né notre projet rocket-swagger, qui prend en charge la génération d’un fichier swagger.yaml à partir de code Spring Boot Webflux.

Rocket Swagger

A partir du code fourni pour JaxRS, nous avons adapté l’implémentation pour prendre en charge les annotations Spring plutôt que celles de JaxRS. Par exemple, @GET ou @POST de JaxRS deviennent @GetMapping ou @PostMapping pour Spring. De plus, nos projets backend utilisant Webflux, nous avons ajouté la prise en charge native des Mono et des Flux retournés par nos contrôleurs Spring. Enfin, nous avons fait un gros travail de refactor sur le code afin qu’il passe la validation Checkstyle de notre intégration continue.

Au final, nous avons publié le projet rocket-swagger en Open Source sur Github, disponible aussi sur Maven Central pour vos projets Maven.

Configuration du plugin Maven

La génération des API se trouve dans un projet d’assembly dédié qui n’a pour seul objectif que la génération de la doc d’API.

Voilà ce que donne la configuration du plugin swagger-maven-plugin pour prendre en compte nos modifications :

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <configuration>
        <configurationFilePath>${project.build.directory}/classes/openapi-configuration.yaml
        </configurationFilePath>
        <outputFileName>swagger</outputFileName>
        <outputPath>${project.build.directory}/classes</outputPath>
        <outputFormat>YAML</outputFormat>
        <resourcePackages>fr.irun</resourcePackages>
        <prettyPrint>true</prettyPrint>
        <readerClass>fr.irun.openapi.swagger.readers.SpringOpenApiReader</readerClass>
        <scannerClass>fr.irun.openapi.swagger.SpringOpenApiScanner</scannerClass>
        <modelConverterClasses>
            fr.irun.apidoc.converter.ApiDocModelConverter
        </modelConverterClasses>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>resolve</goal>
            </goals>
        </execution>
    </executions>
</plugin>

configurationFilePath Contient la description et les variables générales de la documentation
resourcePackages: Pour ne lire que nos classes
scannerClass: La classe de scan qui va chercher les classes annotées @RestController
readerClass: La classe reader modifiée qui prend en compte Spring plutôt que JaxRS.
modelConverterClasses: Un converter custom, qui prend en charge nos classes d’entité spécifiques en utilisant un object mapper configuré pour notre environnement. Il n’est pas inclus dans la librairie rocket-swagger.

Conclusion

Cette documentation est en place sur nos développements Spring Webflux depuis plusieurs mois, et sert de référence lors de nos échanges front/back. N’hésitez pas à tester cette implémentation sur vos projets et à nous faire vos retours sur github dans le projet i-Run/rocket-swagger.