Cet article fait partie d’une série. Retrouvez tous les liens sur la page de sommaire.

Sur les différents projets auxquels j’ai pu participer, une tâche récurrente faisait toujours peur à l’équipe de Dev : écrire la documentation technique !! Et particulièrement quand il s’agit de documenter des services que l’on expose.

Bien sûr chaque équipe à sa propre façon de documenter son application. Que cela passe par un wiki, on bon vieux Word, un Swagger, un projet SoapUI ou Postman, chaque approche aura ses avantages et ses inconvénients, par exemple :

• Dans un document Word
  • Rapide à faire, fastidieux à maintenir
  • Ne fait pas partie de la fabrication, donc facile à déprioriser
• Rédiger et maintenir un Swagger à la main
  • Très consommateur
• Générer un Swagger via annotations dans notre code
  • Généré automatiquement mais non bloquant en cas d’erreur
  • Difficile d’obtenir un rendu final avec tous les éléments souhaités
• Création d’un wiki
  • Pratique d’accès mais fastidieux à maintenir et à mettre en page
• Documenter via un projet SoapUI
  • Peut être intégré dès la phase de conception
  • Permet une approche TDD
  • Peut être intégré dans une plateforme d’intégration continue
  • Granularité et gestion de version complexe (un seul fichier XML en version gratuite)
  • Et tout ce qu’on va décrire après (comment ça je ne suis pas objectif ??)

Personnellement, je vote pour un ou plusieurs projets SoapUI, et pour commencer, on va se poser quelques questions :

1. Qu’est-ce que je veux documenter ?
2. Pour qui ?
3. Quel sera l’usage de mon projet ?

Que l’on veuille communiquer aux équipes qui appellent notre API, avoir un référentiel interne ou un outil de tests, différents projets pourront être mis en place.

Partager avec l’extérieur

Le propre de la documentation, c’est d’être lu !! Ça peut paraître simple, mais c’est la base. Utiliser un outil réputé, c’est aussi rendre accessible la lecture du projet au plus grand nombre.

Créer un projet simple listant tous vos services, et comment les appeler, va permettre de communiquer facilement avec l’extérieur. On pourra retenir quelques éléments :

• Un projet packagé facile à partager
• Des appels testés, qui fonctionnent, et explicites pour une équipe extérieure à la votre
• Vous maîtrisez ce que vous partagez, les environnements que vous laissez accessibles en mode test
• Ça permet aux équipes externes d’avoir un moyen rapide de vérifier si vous services sont UP !!!

C’est fort pratique, et ça vous permettra d’être bien vu par les autres équipes. Si vous préférez recevoir une documentation lisible et utilisable, eux aussi

Pour l’équipe de Dev

Avoir un référentiel de nos appels vers l’extérieur

Sur tous mes derniers projets, j’ai toujours créé un projet SoapUI du genre “Utile : les services qu’on appelle”. Dès la phase de conception, on sait qu’on va avoir besoin d’appeler un référentiel externe, une brique d’authentification, un service de création de commande, etc… Autant tout documenter à un seul endroit ! 

En général dans ce projet, je vais mettre : 

• Un ‘REST Servicepour chaque service externe à appeler
• Au moins un ENDPOINT pour chaque ‘REST Service’ (si plusieurs cadres/environnements on pourra les compléter au fur et à mesure)
• Au moins un exemple d’appel de chaque méthode utilisée par mon équipe
• Des petits bouts de scripts utiles (on y reviendra plus tard)
• Des appels que je refais régulièrement

Concrètement, cela va donner un mini projet de ce genre : 

Les avantages d’avoir ce genre de projet :

• Je peux vérifier rapidement la disponibilité d’un service externe, sans avoir à passer par mon code
• Je documente directement les infos que me transmet l’équipe qui gère ce service
• Je peux tester les paramètres d’appel à un service rapidement
• J’ai une liste de toutes les méthodes qu’on appelle
• Je teste rapidement si une mise à jour a été faite
• Je peux facilement créer des mocks, extraire un résultat pour mes tests unitaires, avoir le format de réponse attendu

Accueil d’un nouvel équipier dans l’équipe

Dans une précédente expérience, j’avais rejoint un projet démarré depuis quelques semaines, encore en phase de lancement en interne. La documentation Word était en cours d’écriture, tous les services exposés par l’API développée n’étaient pas référencés, les subtilités de formats ou de paramètres n’en faisaient pas partie.

Mon premier réflexe avait été  d’initier un projet, juste pour tester nos appels, en découvrir les méandres

Avoir un projet de type “Catalogue de services” va permettre d’identifier en un seul regard tout ce que permet de faire notre API. C’est un point d’entrée simple dans une équipe déjà lancée.

Si ce projet contient des TestSuites avec des tests fonctionnels, c’est encore mieux.

On va pouvoir décrire les enchaînements d’appels récurrents, les résultats attendus par nos appels. Ça peut être un complément idéal à une documentation textuelle pour l’accueil d’un nouvel équipier.

Documenter l’utilisation d’un framework ou progiciel

Dernier exemple pour cet article, j’alimente régulièrement certains projets (perso ou pas) pour tester des API ou faire des POC rapides.

Pour un petit projet pour jouer avec les API de Strava et de Twitter, ou bien comme ci-dessous, au fil des projets pour me faire mes propres UseCases de l’API d’un progiciel. Cela me permet de savoir ce que l’on peut faire, tester des paramètres, être indépendant du réseau pour ne pas aller chercher une doc en ligne, et surtout capitaliser pour moi ou mon équipe.

Les deux premiers articles de la série étaient très descriptifs, mais c’est promis, dès le prochain on commence à regarder du code

Pour retrouver les autres articles concernant SoapUI, l’index de la série a été mis à jour.