Entrée.

Chères lectrices, chers lecteurs, je vais aujourd'hui partager avec vous une recette de ma grand-mère, qui m'a appris à sublimer les rouleaux de printemps au concombre. Pour cela, nous allons avoir besoin des ingrédients suivants :

• Asciidoctor
• Cucumber
• SpringBoot (Spring MVC en fait, mais comme est on en pleine hype microservices, faut être SWAG, sinon j'aurais dit JHipster)

Mais avant de commencer à trancher dans le lard, intéressons-nous à la base-même du plat du jour, AsciiDoc : AsciiDoc est un langage balisé léger du même gabarit que le plus connu MarkDown. N'étant un expert ni de l'un ni de l'autre, je ne vais pas créer un débat de goûts et sensations culinaires de chacun d'eux. Sachez juste que selon les auteurs, AsciiDoc a été pensé pour créer toute sorte de document, de la plus simple des notes à (et surtout) une publication entière et professionnelle. Il est complet (c'est à dire sans matière grasse à ajouter) vis à vis de MarkDown et de ce fait, plus complexe. Mais ce qu'il faut retenir avant tout, c'est que l'un ou l'autre vous permettra d'avoir la possibilité de traiter le document que vous écrivez comme du code qui pourrait être versionné : vous pouvez donc utiliser n'importe quel outil de comparaison pour regarder les différences entre 2 versions. Par contre, oubliez les éditeurs WYSIWYG car les langages balisés légers sont faits pour être facilement utilisables et pour se passer des éditeurs de texte comme Word.

Notre ingrédient principal est donc AsciiDoctor, un outil open-source permettant de transformer des documents AsciiDoc en documents HTML5, PDF, EPUB3 et autres. Il se différencie grâce à son intégration simplifiée à des projets à base de Ruby, Javascript, Java et autres langages basés sur la JVM. Il permet aussi d'étendre le langage AsciiDoc afin de pouvoir récupérer une partie ou l'ensemble d'un fichier tierce, se révélant alors très pratique pour extraire des parties de votre code source. Il peut aussi être étendu afin d'intégrer des graphes ou encore de customiser la sortie afin de créer une présentation slideshow.
Son créateur, Dan Allen, est très actif pour améliorer sans cesse l'outil. Il fait aussi beaucoup de présentations sur ce sujet, notamment aux derniers Devoxx France, Belgique et Maroc.

Lorsque vous faites du BDD, il y aura forcément un moment où vous avez besoin de décrire vos scénarios et allez en profiter pour baser vos tests dessus. Pour son côté rafraichissant et peu calorique, Cucumber est une solution de choix, avec l'écriture des fameux Given-When-Then en syntaxe Gherkin. Ici, nous allons transformer les scénarios et leurs résultats en documentation grâce à CukeDoctor. CukeDoctor s'appuie sur AsciiDoctor pour transformer les résultats JSON de Cucumber en document HTML5 qui indiqueront, à la manière d'un report, les différentes étapes et le résultat de chaque scénario.

Enfin, pour le dressage et la cuisson, nous allons utiliser Spring Boot et pour documenter son API REST basée sur Spring MVC, nous ajouterons Spring REST Docs. Ce projet et plugin maven va vous permettre de faire 2 choses à la fois : tester votre API REST (comme Spring MVC Tests) et en sortir une documentation AsciiDoctor. Chacun de vos tests sur les controllers va générer des mini-documents AsciiDoctor que vous importerez afin de donner des exemples d'appels et d'indiquer les différents paramètres, leur signification et les valeurs qu'elles peuvent prendre. Fini donc le plat préparé Swagger du supermarché, place à l'authentique documentation à la manière de GitHub !

Plat principal

Sortez vos outils, vos tablettes à découper et de quoi noter. Commençons donc par télécharger un moule tout fait d'application maven avec spring boot web (pensez donc à sélectionner le starter Web) sur https://start.spring.io/.

AsciiDoctor

Nous allons maintenant nous intéresser à écrire une documentation remplaçant les spécifications fonctionnelles et techniques en asciidoctor.
Pour cela, le plus simple est de rajouter un plugin maven au pom.xml (dans la partie build > plugins donc):

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <executions>
        <execution>
            <id>ascidoctor-html5-documentation</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDirectory>src/main/asciidoc/specifications</sourceDirectory>
                <backend>html5</backend>
                <sourceHighlighter>highlightjs</sourceHighlighter>
                <preserveDirectories>true</preserveDirectories>
                <attributes>
                    <sourceDir>${project.basedir}/src/main/java</sourceDir>
                    <data-uri/>
                    <toc2/>
                    <toclevels>4</toclevels>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

L'exécution ascidoctor-html5-documentation permet de générer un document HTML5 (le paramètre backend) à partir du dossier source situé dans src/main/asciidoc/specifications, de préserver la hiérarchie des répertoires sources d'AsciiDoctor et d'avoir une table des matières à 4 niveaux, affichée sur le côté (toc2).¹.

Voilà ! Maintenant vous pouvez commencer à écrire de l'asciidoctor dans un fichier .adoc:

= Projet DEMO - Spécifications Fonctionnelles
================
:author: Yvan VU
:data-uri:
:icons: font

== Introduction

=== Objet du document

Le présent document constitue les spécifications fonctionnelles de l'application DEMO.

=== Documents de référence

D'autres documents sont disponibles pour l'application DEMO :

[cols="1,2", options="header"]
|===
|Titre
|Description
|<<../techniques/index.adoc#,Spécifications_techniques>>
|Spécification techniques du projet DEMO
|===

////
TODO : mettre le lien vers les documents en question
|<<../scenarios.adoc#, Rapport cucumber >>
|Rapport de scénarios du projet DEMO
|<<../index.adoc#,api_rest_docs >>
|Documentation de l'API REST du projet DEMO
////

== Description générale

=== Enjeux

...

=== Usage

TIP: ceci est un pro-tip

==== API REST

l'API REST permettra à chaque client d'utiliser l'application via des appels #http#.

==== FizzBuzz

Lorsque l'on appelle le service FizzBuzz, on lui donne en paramètre un entier. Le service retournera alors :

* l'entier passé en paramètre *sauf*
* si le paramètre est un multiple de *3*, le service retournera *Fizz*
* si le paramètre est un multiple de *5*, le service retournera *Buzz*
* si le paramètre est un multiple de *3 et 5*, le service retournera *FizzBuzz*

Comme vous pouvez le voir, la syntaxe d'AsciiDoctor a été faire pour être la plus simple possible afin de ne pas polluer l'information. Les niveaux des titres sont définis par les = et nous avons entre autres créé un tableau, ( les |=== et | ), des commentaires et une liste via *.

On peut aussi extraire une partie du code source :
(dans le fichier .adoc)

[source,java]
----
include::{sourceDir}/com/example/domain/FizzBuzz.java[tags=implementation]
----

include permet donc d'inclure le contenu d'un fichier dans la documentation, grâce aux tags, on ira chercher le code java situé entre les balises // tag::implementation[] et // end::implementation[] dans la classe FizzBuzz.

Comme on a défini l’exécution du plugin durant la phase generate-resources, la transformation des documents en html se fera avant la compilation.

Via le build maven, après un simple maven compile, on pourra voir un joli document html se générer dans target/generated-docs/fonctionnelles/index.html :

et pour l'extrait de code :

Voilà, avec un peu de pratique vous maîtriserez AsciiDoctor et écrirez vos propres recettes de cuisine ! Maintenant vous n'avez plus qu'à convaincre votre équipe ou toute personne non technique d'écrire la documentation en asciidoctor et non plus sous word !

CukeDoctor

Vous avez donc vos plats à base de Cucumber et des scénarios Gherkin qui n'attendent qu'à être sortis dans une jolie page web montrant que tout est beau :

Là aussi, on va ajouter le plugin maven suivant ²:

<plugin>
    <groupId>com.github.cukedoctor</groupId>
    <artifactId>cukedoctor-maven-plugin</artifactId>
    <version>0.6.1</version>
    <configuration>
        <outputFileName>scenarios</outputFileName>
        <outputDir>generated-docs</outputDir>
        <toc>left</toc>
        <numbered>true</numbered>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>execute</goal>
            </goals>
            <phase>install</phase>
        </execution>
    </executions>
</plugin>

La configuration ici présente indique que l'on va générer deux fichiers scenarios.adoc et scenarios.html où tout le report des tests Cucumber sera présent.

Le travail supplémentaire s'arrête là : vous avez déjà écrit tout ce qu'il fallait. Vous avez juste à lancer le build maven install et vous obtiendrez alors la sortie suivante (toujours dans target/generated-docs/scenarios.html :

Bon, je vous l'accorde, ceci n'était que pour vous montrer qu'on peut intégrer dans son build l'automatisation de tâches AsciiDoctor, car cela reste un report assez basique au final.
Mais comme il y aussi la génération d'un .adoc à côté du .html, vous pourrez toujours l'importer dans un document asciidoctor, moyennant quelques configurations à faire.

Il existe bien sûr d'autres alternatives pour documenter ses tests et rapports Cucumber, du plugin Jenkins au projet github d'un collègue.

Retrouvons-nous après une courte page de publicité : Vous souhaitez en faire plus avec vos concombres ? Vous en avez marre de juste les découper en rondelle et les présenter en apéro à ses amis? Découvrez Tzatziki, une recette onctueuse préparé par Arnauld Loyer lui-même !

Spring REST Docs

Attention, c'est à cet endroit qu'on utilise notre ingrédient principal, l'ingrédient que l'on aime tous : Spring !

Les rouleaux de printemps, c'est facile à faire. Idem ici aussi, on commence par rajouter la levure chimique à notre maven puis 2 nouvelles tâches à exécuter dans la partie build (qui commence à grossir maintenant...) :
l'une pour définir et filtrer les classes de tests pour Spring REST Docs, l'autre, qui est une nouvelle exécution du plugin AsciiDoctor, pour transformer le document de l'API REST en html.

<!-- dans dependencies -->
<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>1.0.0.RELEASE</version>
    <scope>test</scope>
</dependency>
<!-- à ajouter dans executions de asciidoctor-maven-plugin, après l'execution du ascidoctor-html5-documentation -->
<execution>
    <id>rest-api</id>
    <phase>package</phase>
    <goals>
        <goal>process-asciidoc</goal>
    </goals>
    <configuration>
        <sourceDirectory>src/main/asciidoc/api</sourceDirectory>
        <backend>html5</backend>
        <sourceHighlighter>highlightjs</sourceHighlighter>
        <attributes>
            <sourceDir>${project.basedir}/src/main/java</sourceDir>
            <generatedDir>${project.build.directory}/generated-snippets</generatedDir>
            <data-uri/>
            <toc2/>
            <toclevels>4</toclevels>
        </attributes>
    </configuration>
</execution>
<!-- à ajouter build > plugins -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.18.1</version>
    <executions>
        <!--tests for api rest documentation-->
        <execution>
            <id>api-rest-documentation-tests</id>
            <goals>
                <goal>test</goal>
            </goals>
            <configuration>
                <includes>
                    <include>**/*RESTDocumentation.java</include>
                </includes>
                <systemPropertyVariables>
                    <org.springframework.restdocs.outputDir>
                        ${project.build.directory}/generated-snippets
                    </org.springframework.restdocs.outputDir>
                </systemPropertyVariables>
            </configuration>
        </execution>
    </executions>
</plugin>

L’exécution supplémentaire de AsciiDoctor pourrait être fusionnée avec celle de la 1ère étape : si vous souhaitez le faire, vous devrez déplacer la génération asciidoctor après la phase de tests. En effet, la phase de tests génère les rapports Cucumber et Spring Rest Docs en asciidoctor, la transformation asciidoctor pourra alors l'inclure et s'exécuter dans une phase tardive comme la package.

Nos tests de webservices REST réalisés avec mockmvc sont donc écrits comme ceci :

@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = {DemoApplication.class})
@WebAppConfiguration
public class FizzBuzzRestTests {

    @Rule
    public final RestDocumentation restDocumentation = new RestDocumentation("target/generated-snippets");
    @Autowired
    private WebApplicationContext context;
    @Autowired
    private ObjectMapper objectMapper;
    private MockMvc mockMvc;

    @Before
    public void setUp() {
        objectMapper.findAndRegisterModules();
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
                .apply(documentationConfiguration(this.restDocumentation))
                .build();
    }

    @Test
    public void checkCodeValiditySimple() throws Exception {
        this.mockMvc.perform(
                get("/fizzbuzz/{input}", 30)
                        .accept(MediaType.APPLICATION_JSON)
                        .contentType(MediaType.APPLICATION_JSON))
                .andDo(print())
                .andExpect(status().isOk())
                .andExpect(content().string("{"result":"FizzBuzz"}"))
                .andDo(document("fizz-buzz",
                                pathParameters(
                                        parameterWithName("input").description("Un paramètre entier.")),
                                responseFields(
                                        fieldWithPath("result").description("Le résultat de l'appel : L'entier passé en paramètre, Fizz, Buzz ou FizzBuzz"))
                        )
                );
    }

}

Ici, dans le test reposant sur mockmvc du controller correspondant à /fizzbuzz/{entier}, on a ajouté dans le @Before la configuration pour utiliser REST Docs. Puis dans le test, on documente dans le andDo(document(...)) les paramètres en entrée et sortie. Cela veut dire que si vous avez déjà des tests sur vos controllers Spring MVC, vous n'avez qu'à rajouter cette partie.
Pour l'exemple, on retourne un object JSON contenant le résultat du fizzbuzz.

Lorsque ce test sera exécuté via maven, plusieurs documents seront générés dans target/generated-snippets/fizz-buzz:

• curl-request.adoc
• http-request.adoc
• http-response.adoc
• path-parameters.adoc
• response-fields.adoc

Vous pouvez alors utiliser ces documents en les incluant à votre documentation pour l'API REST :

=== GET /fizzbuzz/{entier}

Requête GET pour récupérer le résultat d'un fizzbuzz particulier d'un {entier} passé en paramètre de l'URL.

Requête curl :
include::{generatedDir}/fizz-buzz/curl-request.adoc[]

Requête http :
include::{generatedDir}/fizz-buzz/http-request.adoc[]

Paramètres :
include::{generatedDir}/fizz-buzz/path-parameters.adoc[]

'''

Réponse http :
include::{generatedDir}/fizz-buzz/http-response.adoc[]

Champs de la réponse :
include::{generatedDir}/fizz-buzz/response-fields.adoc[]

=== POST ...

...

Le plugin maven va donc transformer ces tests en une documentation asciidoctor (qui sera à son tour transformée en html via l'étape du plugin maven asciidoctor) consultable dans target/generated-docs/index.html :

Spring Rest Docs est capable de documenter les paramètres dans le path aussi bien que dans la request, de gérer l'hypermedia, les headers et les payload en JSON ou XML.
Votre exemple d'appel pouvant très bien comporter des champs optionnels, vous pouvez spécifier le type d'un champ afin que Spring Rest Docs ne le mette pas à Null.
Du coup, vous pouvez faire plusieurs exemples d'appels et puisque vous avez juste à extraire la partie document() dans une méthode, vous ne documentez qu'à un seul endroit du code !

Avec ceci, vous avez une documentation de votre API REST qui est claire, concise, et qui, en se reposant sur vos tests, devient vivante car tout changement d'api vous obligera à revoir la documentation de vos exemples.

Dessert

Grâce à ces 3 solutions, vous avez maintenant la possibilité d'avoir une documentation vivante de votre code qui servira :

• au métier pour la partie spécifications (et évitera d'aller rechercher dans vos mails le fameux "[FINAL]LES_VERITABLES_ET_UNIQUE_COMPLETE_specifications_v13.87(copier)(6).docx")
• aux autres développeurs qui interviendront tôt ou tard sur le code et pourront s'appuyer sur les différents documents
• aux personnes qui utiliseront votre API et auront des exemples d'appels

Vous venez donc de sublimer votre délicieux projet Spring. Vous ne l'utilisez pas à votre travail ? Pas de problème, la 1ère partie est la plus importante et la plus générique.

On peut aussi noter que l'ensemble de ces solutions n'impactent aucunement l'environnement de travail puisqu'elles sont directement intégrées via des plugins maven.

Reste ensuite que votre documentation doit être déposée sur un serveur web accessible par les personnes visées. Personnellement (et en tant que réinventeur d'omelette), j'ai intégré un script à la fin de mon build Jenkins pour copier les pages html sur un répertoire de serveur apache disponible en intranet. Sinon, vous pouvez toujours l'intégrer à un maven site.

Vous pouvez retrouver le code utilisé pour cet article sur ce GitHub.

Yvan Vu

Plus de publications

This author does not have any more posts.