Continuous Documentation – Exemple de mise en place

Parmi les livrables d’un projet, la documentation est celle qui assurera sa pérennité. Dans le cadre d’une application, la documentation technique est la garante des fonctionnalités disponibles, de leurs usages mais aussi de son architecture, son intégration et son déploiement. Par conséquent, la documentation est vouée à vivre au rythme de l’évolution de l’application, et trouve naturellement sa place aux côtés du code source de l’application. Ainsi, quels sont les outils les plus adaptés à la rédaction de la documentation pour la faire cohabiter avec les sources ?

La documentation au plus proche du code source

Tout d’abord, certains outils de gestion de sources – tel que GitHub et GitLab – proposent des fonctionnalités dédiées à la documentation comme un wiki intégré et l’interprétation des fichiers MarkDown et AsciiDoc, deux formats de texte pour la rédaction de documentations. Ces formats simples on l’avantage d’être de simples fichiers textes et sont par conséquent facilement exploitable dans un outil de gestion de sources, contrairement aux formats Word et LibreOffice. L’emplacement de la documentation technique est alors idéale car au plus proche de l’application : elle pourra évoluer et être versionnée en même temps que le code.

Cependant, cela ne convient pas à tous les usages : le référentiel de codes est rarement ouvert à tous en entreprise, et la consultation de la documentation via GitHub ou GitLab n’est pas toujours le format le plus adapté pour la consulter ou la partager. C’est pourquoi, des formats plus traditionnels comme le HTML ou le PDF sont souvent plus pratiques à l’usage, à la publication, éventuellement pour l’impression ou encore pour un classement dans une GED.

A l’instar de HTML/CSS, les documents MarkDown et AsciiDoc peuvent servir à la génération d’un document plus lisible et esthétique aux formats HTML ou PDF par exemple. En outre, AsciiDoctor est un outil pour convertir les documents AsciiDoc vers HTML, PDF ou encore DocBook.

asciidoctor

Générer la documentation à la construction de l’application

Intégrer la génération de la documentation avec la construction de l’application garantie la livraison d’une documentation à chaque version. Dans cette optique, le plugin asciidoctor-maven-plugin convertit les documents AsciiDoc pour les projets Maven. Les projets Gradle ne sont pas en reste et disposent d’un plugin équivalent : asciidoctor-gradle-plugin.

En ce qui concerne le plugin Maven, son utilisation est des plus simple :

  • déclarer le plugin dans votre fichier pom.xml,
  • placer votre documentation asciidoc dans src/main/asciidoc.

La documentation sera alors générée dans target/generated-docs en même temps que la construction du projet.

Exemple d’utilisation du asciidoctor-maven-plugin:
<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>1.5.3</version>
  <executions>
    <execution>
      <id>generate-docs-html</id> <!-- <2> -->
      <phase>prepare-package</phase>
      <goals>
        <goal>process-asciidoc</goal>
      </goals>
      <configuration>
        <backend>html</backend>
        <doctype>book</doctype>
        <attributes>
          <snippets>${snippetsDirectory}</snippets>
        </attributes>
      </configuration>
    </execution>
  </executions>
</plugin>

<1> Dépendances requises pour supporter le PDF.
<2> La première exécution du plugin génère la documentation en HTML.
<3> La seconde exécution génère la documentation en PDF.

 

Documenter les API REST

La documentation d’une API est une partie des plus fastidieuses. En effet, celle-ci décrit l’utilisation de chaque services – que ce soit la requête attendue ou la réponse qui sera émise – et les différents cas d’usage. Un travail d’autant plus pénible que les contrats de services seront amenés à évoluer au fur-et-à-mesure des versions.

Swagger et JSONDoc : solutions invasives

A cette fin, des outils tels que Swagger ou JSONDoc sont populaires. Ils agrémentent tous les deux vos API afin d’exposer votre documentation, exploitable ensuite à travers une interface Web. Séduisantes au premier abord, elles vous permettent également de tester directement vos API.

Néanmoins, ces solutions sont intrusives dans le code de votre application. D’abord, elles imposent de les embarquer dans votre application et ajoutent une surcouche à vos API même en production. De plus, leur fonctionnement implique d’insérer des annotations dédiées à la documentation au cœur même du code source, sur chaque services de l’API. Une idée séduisante initialement : avoir la documentation au plus proche du code. Malheureusement, cela tend rapidement à réduire la lisibilité du code, et limite la maintenance de la documentation uniquement aux développeurs.

Par ailleurs, ces outils ne répondent que partiellement au besoin de documentation des API REST, notamment ils ne permettent pas de décliner aisément les différents cas d’utilisation et se limitent à la seule description des services, des champs à renseigner ou des réponses. Ils n’adressent pas non plus les liens HATEOAS. Dernier mauvais point, ils ne peuvent pas être inclus dans une documentation traditionnelle comme un guide de l’utilisateur.

Spring RESTDoc : une approche via les tests

Pour ces motifs, Spring RESTDocs propose une autre approche qui combine les avantages d’une documentation écrite manuellement et de la documentation générée. Ainsi, ce framework s’introduit également dans votre application, mais uniquement dans la phase de tests : il n’introduira alors en aucun cas de désagrément à vos services en production. Il n’y sera même pas présent. Son fonctionnement reprend l’idée de s’inviter dans le code source de votre application pour être au plus près de vos API, mais contrairement à Swagger ou JSONDoc, le code de votre application n’est pas impacté. En effet, Spring RESTDocs vient enrichir vos tests unitaires !

Exemple de test unitaire incluant de la documentation:
this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document("index",
                responseFields( 
                        fieldWithPath("contact.email")
                                .description("The user's email address"), 
                fieldWithPath("contact.name").description("The user's name"))));

Dorénavant, lors de la construction du projet au moment où les tests seront exécutés, Spring RESTDocs générera des fichiers AsciiDoc contenant les requêtes et les réponses simulées lors du tests ainsi que les descriptions ajoutées dans les tests. Ensuite, ces documents pourront ensuite être inclus dans la documentation que vous avez produit pour décrire un cas d’usage. De cette façon, elle est non seulement plus lisible et plus détaillé, mais également toujours en concordance avec vos tests et par conséquent avec votre code.

Un projet exemple est disponible sur GitHub.