Générez votre documentation avec apiDoc


2 min read
Générez votre documentation avec apiDoc

apiDoc permet de créer une documentation pour une API grâce aux commentaires dans votre code. L'outil intègre un historique des versions, une comparaison entre ces versions, la documentation est entièrement paramétrable. apiDoc est utilisable pour de nombreux langages (PHP, JS, Python, Ruby, Java ...) en fait pour tous ceux qui  acceptent des commentaires multi-ligne. La mise en place est extrêmement  simple et rapide.

Par exemple, voici comment créer une documentation en PHP :

/**
 * @api {get} /client/:id Sélectionne un client
 * @apiName GetClient
 * @apiGroup Client
 *
 * @apiParam {Number} id Client unique ID.
 *
 * @apiSuccess {String} firstname Prénom du client.
 * @apiSuccess {String} lastname  Nom du client.
 */

Retrouvez une démo en ligne : Démo en ligne disponible !

Installation

Vous devez au préalable avoir installé nodeJs.

npm install apidoc -g

L'installation est terminée ... Vous pouvez tester le bon fonctionnement en tapant la commande : apidoc -h

Configuration

A la racine de votre dossier vous devez créer un fichier apidoc.json. Les infos sur ce fichier ici : http://apidocjs.com/#configuration.

{
    "name": "Monsite API",
    "version": "0.1.0",
    "description": "Documentation API",
    "url" : "http://api.exemple.fr"
}

Première documentation

/**
 * @api {get} /client/:id Sélectionne un client
 * @apiName GetClient
 * @apiGroup Client
 *
 * @apiParam {Number} id Client unique ID.
 *
 * @apiSuccess {String} firstname Prénom du client.
 * @apiSuccess {String} lastname  Nom du client.
 */

L'exemple ci-dessous crée la documentation pour une fonction qui permet de récupérer les données d'un client :

apidoc -i app/ -o doc/

Cette commande crée la documentation de l'application présente dans app/ et envoi cette documentation dans le dossier doc/. Voilà la documentation générée :

Vous pouvez paramétrer des exemples de réponse, d’erreurs, des headers, des permissions ... Je vous invite à jeter un œil à la documentation officielle qui est très complète : http://apidocjs.com

Merci d'avoir suivi cet article jusqu'au bout ! ❤️


Un bot Twitter pour liker
Previous article

Un bot Twitter pour liker

Créer un bot twitter qui like des tweets selon un mot clé en 20 lignes ? C'est parti ! Comme vous l'aurez compris nous allons créer un

La méthode Kanban
Next article

La méthode Kanban

Kanban est une méthode de gestion du flux de travail sous  forme de taches. D'ailleurs, Kanban signifie "carte de signalisation" en  japonais. La méthode repose


GO TOP