Dans le chapitre précédent, nous avons vu comment utiliser Git pour faire de bons commits, créer un README qui reflète bien votre projet, et utiliser Read the Docs pour publier votre documentation.
Dans ce chapitre, nous allons voir ensemble comment écrire de la documentation pour un cas particulier : une API.
Écrivez la documentation de votre API
Le but des API est d'être utilisée par de nombreux développeurs, souvent même extérieurs à votre projet ou entreprise. Dans ce contexte, une documentation accessible et facilement exploitable est une condition préalable au développement des API. Il est important d’avoir une documentation toujours à jour quand le code/les fonctionnalités de l’API évoluent.
C’est d’autant plus important quand le modèle de développement est centré sur le travail collaboratif, que ce soit au sein de l’entreprise (privé) ou bien dans le monde open source (public). En d’autres termes, synchronisez toujours les changements sur l’API et la documentation associée !
Que doit contenir votre documentation d'API ?
À titre d’exemple, regardez la documentation de l’API de Dropbox que vous connaissez certainement. On y trouve tous les éléments requis : les endpoints (HTTP reference, l’authentification), les exemples de code et les paramètres (API Explorer), le changelog (pour les changements depuis les versions antérieures).
Le cycle de vie d’une documentation d’API
Comme dans tout travail de conception, la documentation d’une API suit un cycle de vie particulier :
La création : grâce aux outils en ligne, on peut facilement partager avec nos clients ou nos collègues la structure de l’API pour recueillir leur feedback et les demandes d’évolution des fonctionnalités, avant même de les coder.
Le test : on peut facilement évaluer la cohérence des réponses des endpoints de l’API via des formulaires.
Le partage de la documentation : en liant son repository Git avec la documentation, on permet une totale synchronisation au sein de l’équipe. Ainsi, la documentation vit à côté du code, ce qui représente un avantage indéniable aujourd’hui. Enfin, l’équipe peut se mettre d’accord sur les règles syntaxiques et sémantiques métier à respecter en écrivant la documentation, afin d’assurer sa cohérence.
Publiez votre documentation avec Apiary
Sans vouloir passer trop de temps sur l’outil, je vous propose de voir les différentes bonnes pratiques qu’Apiary propose dans le cycle de vie de la documentation.
Apiary propose un workflow qui respecte le cycle d'une documentation d'API, que nous avons vue à la section précédente. Voyons ensemble les points essentiels.
Créez votre documentation avec Apiary
À la création d’une nouvelle API, Apiary propose une visualisation en 2 parties. À gauche, un template de documentation d’API publique (sans authentification) générique, et à droite le live preview qui permet de visualiser en temps réel les modifications que vous apportez.
Regardons plus en détail le code à gauche.
Cette interface propose un code prérempli avec quelques éléments :
le type de format possible pour décrire l’API (Apiary permet de le faire en JSON ou en Markdown, par exemple) ;
le type d’hébergement pour l’API. Apiary propose 3 types d’hébergement ;
un titre rapide ainsi qu’une description ;
les éléments pour interroger les endpoints GET et POST de l’API.
FORMAT: 1A
HOST: https://polls.apiblueprint.org/
# Polls
Polls is a simple API allowing consumers to take part in polls and view their results.
## Questions Collection [/questions]
### List All Questions [GET]
+ Response 200 (application/json)
[
{
"question": "Favourite programming language?",
"published_at": "2015-08-05T08:40:51.620Z",
"choices": [
{
"choice": "Swift",
"votes": 2048
}, {
"choice": "Python",
"votes": 1024
}, {
"choice": "Objective-C",
"votes": 512
}, {
"choice": "Ruby",
"votes": 256
}
]
}
]
### Create a New Question [POST]
You may create your own questions using this action. It takes a JSON
object containing a question and a collection of answers (called “choices”)
+ Request (application/json)
{
"question": "Favourite programming language?",
"choices": [
"Swift",
"Python",
"Objective-C",
"Ruby"
]
}
+ Response 201 (application/json)
+ Headers
Location: /questions/2
+ Body
{
"question": "Favourite programming language?",
"published_at": "2015-08-05T08:40:51.620Z",
"choices": [
{
"choice": "Swift",
"votes": 0
}, {
"choice": "Python",
"votes": 0
}, {
"choice": "Objective-C",
"votes": 0
}, {
"choice": "Ruby",
"votes": 0
}
]
}Je vous recommande de compléter ce premier template grâce aux éléments dont vous avez besoin (authentification, paramètres, etc.), pour voir les changements directement dans le live preview.
Testez votre documentation avec Apiary
Une fois la documentation créée, la phase suivante du cycle consiste à la tester pour évaluer si elle correspond bien aux usages envisagés.
Apiary propose cette possibilité de manière native, ce qui est très pratique. L’interface permet de tester les endpoints de l’API en utilisant un formulaire avancé. Cette option est accessible directement depuis l’éditeur d’Apiary.
Collaborez autour de votre documentation avec Apiary
La fonctionnalité que je préfère avec Apiary, c’est la facilité avec laquelle on peut synchroniser sa documentation d’API avec un repository Git public en quelques clics.
Une fois la synchronisation effectuée, l’éditeur d’Apiary change légèrement d’apparence. Il laisse apparaître un bouton “Push” en haut à droite, qui vous permet de commiter vos changements, et un bouton “Branch: master” qui vous indique dans quelle branche de votre code vous vous trouvez.
Ici, vous pouvez voir apparaître en haut à droite une infobox pour le commit à venir.
On retrouve maintenant le fichier de la documentation directement dans le repository. Ainsi, Apiary propose une intégration complète dans Git pour favoriser le travail d’équipe.
En résumé
Dans ce chapitre, nous avons vu que :
la documentation de votre API est cruciale pour assurer un partage au sein de votre équipe ou pour des utilisateurs potentiels ;
elle devrait comporter :
la manière de s'authentifier s’il s’agit d'une API privée,
la définition des endpoints,
les paramètres éventuels,
quelques extraits de code,
des exemples de requêtes et de réponses ;
le cycle de vie de la documentation comprend la création, le test et le partage ;
Apiary est une plateforme qui permet notamment de gérer ce cycle pour vos API. Son intégration avec les workflows de Git fournit un outil très puissant pour améliorer la productivité de l’équipe.
Voilà, nous sommes arrivés à la fin de la première partie de ce cours, dans laquelle nous avons abordé les grandes lignes pour écrire une documentation qui permet une amélioration de la lisibilité et de l’évolutivité du code, mais également qui favorise le travail en équipe.
Dans la seconde partie de ce cours, je vous propose de voir comment écrire la documentation technique de vos projets.
