Introduction REST Docs

Les applications s’ouvrent et s’interconnectent de plus en plus. Elles exposent et partagent leurs états via des interfaces qui sont, aujourd’hui, souvent des interfaces sous forme d’API REST avec des microservices. Ces interfaces doivent être documentées afin de faciliter l’accès à nos applications.

La documentation des API publiques LinkedIn, Facebook, Twitter, Google est particulièrement bien faite et elle est parfois comparée à la documentation de nos API en interne et cela nous pousse à passer un temps considérable pour avoir une documentation claire, précise et à jour.

Pour répondre à ce besoin, Spring a mis à disposition une librairie Spring REST Docs qui peut être utilisée pour créer une documentation automatique pour les services REST. Cette possibilité vient en complément des outils comme Swagger (statique et dynamique) avec SpringFox et le HAL Browser qui montrent par l’exemple le fonctionnement des services. HAL Browser

La librairie se base sur Asciidoctor et des extraits de documentation pour générer automatiquement, à la compilation, du texte brut ou du HTML.

Il est aussi possible de générer du Markdown (fichier *.md) qu’il est alors très pratique d’utiliser dans GitLab ou GitHub par exemple. La librairie est utilisée conjointement...