Objectifs et contexte du projet.
-
vue très haut niveau
-
grandes fonctionnalités
-
pour notre application de billetterie, cela donnerait …
Grandes fonctionnalités
Acheter des places pour les JO
Télécharger les billets achetés
Liens vers la documentation existante
Maquettes de l’application
Liens vers la documentation existante
Maquettes de l’application
Spécifications fonctionnelles
Liens vers la documentation existante
Maquettes de l’application
Spécifications fonctionnelles
Documentation de référence de l’API REST
-
doc de référence ⇒ plutôt répandu, on va la générer.
-
et ça tombe bien, mon API REST possède un contrat d’interface !
-
il y a d’autres contrats comme api blueprint, raml, …
-
OpenAPI Specification est le plus populaire (anciennement Swagger)
-
ces informations doivent être présentes dans le contrat d’interface
-
renvoi vers la spécification OpenAPI pour tirer parti au mieux de ces outils
Pas de contrat d’interface ?
-
possibilité de le générer à partir du code source
-
plein d’outils permettant de le faire, venant du monde Java/Spring j’évoquerai SpringDoc
-
dispo pour tous les langages et framework : .NET, Node.js …
Pas d’API REST ?
-
Javadoc
-
JSDoc
-
Asciidoclet, Javadoc avec la syntaxe Asciidoc pour apporter plus de richesse et de lisibilité
-
JEP 467 : markdown pour écrire la Javadoc, sorti Java23
-
attention, je ne dis pas qu’il faut utiliser ces outils, certaines personnes considèrent que ça peut polluer ou alourdir le code
-
à vous de voir avec votre équipe