Découverte : 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.
 */
public function listClients($request, $response, $args) {
  $stmt = $this->pdo()->select(['firstname','lastname'])
->from('clients')
->where('id','=',$args['id'])
->execute();
  $client = $stmt->fetchAll();

  return $response->withJson($client, 200);
}

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 ! ❤️

Commentaires