======Documentation des API Rest (docs, tests, mocks)======

==== Différents outils de génération de doc ====
Classement par préférence :
  - [[http://raml.org/|RAML]] : v1.0 (2015-11-03) [Licence MIT]
  - [[https://apiblueprint.org/|API-BluePrint]] : v1A9 (2015-06-08) [Licence MIT]
  - [[http://swagger.io/specification/|Swagger]] : v2.0 (2014-09-08) [Licence Apache, v2.0]
  - [[http://apidocjs.com/|ApiDocJs]] : v0.13.0 (2015-05-08) Permet de générer une doc à partir d'une syntaxe PHPdoc. Simple mais avec peu d'outils liés. [Licence MIT]

===== RAML =====
Site principal : [[http://raml.org/|RAML]] : v1.0 (2015-11-03) [Licence MIT]
  * Permet de rédiger la doc en Markdown.
  * Très similaire à Apiblueprint.
  * Écosystème très riche (plus qu'Apiblueprint).
  * De très nombreux outils (dans différents langage) à disposition : doc, test, designer, mock server...

===== Apiblueprint =====
Site principal : [[https://apiblueprint.org/|API-BluePrint]] : v1A9 (2015-06-08) [Licence MIT]\\
Permet de rédiger la doc en Markdown. Relativement complexe pour se retrouver dans la doc.

=== Ressources ===
  * [[https://apiblueprint.org/| Site officiel]]
    * [[https://raw.githubusercontent.com/danielgtaylor/aglio/master/example.apib|Exemple]] : exemple de fichier markdown.
    * [[https://github.com/danielgtaylor/aglio|Agglio]] : interface de consultation de la doc API Blueprint (PHP). [Licence MIT]
      * [[https://htmlpreview.github.io/?https://raw.githubusercontent.com/danielgtaylor/aglio/blob/master/examples/flatly.html#notes-note-list-get|Rendu]] : Exemple de rendu avec Aglio.
    * [[http://dredd.readthedocs.org/en/latest/|Dredd]] : outils vérifiant la synchro entre l'implémentation des services web et la doc API Blueprint. [Licence MIT]
      * [[https://github.com/stekycz/restful-api-testing/tree/master/chapters|Retour sur les API REST et les outils de tests]], dont Dredd & API Blueprint
    * [[https://github.com/stekycz/cucumber-4-api-blueprint|Cucumber-4-Api-blueprint]] : jonction entre Cucumber (framework de test JS) et Api-blueprint. [Licence MIT]
    * [[https://github.com/localmed/api-mock|Api-Mock]] : créer un serveur qui renvoie les données fournies en exemple pour chaque service web. [Licence MIT]
    * [[https://github.com/kminami/apib2swagger/|Apib2Swagger]] : convertisseur de API Blueprint 1A8 vers Swagger 2.0. [Licence MIT]
  * Pour les tutoriels, voir le site Apiary : 
    * [[https://apiary.io/blueprint|Tutoriel]] : tutoriel pour la création d'une doc API Blueprint.
    * [[https://docs.apiary.io/api_101/api_blueprint_tutorial/|API Blueprint]]
    * [[https://docs.apiary.io/api_101/mson-tutorial/|MSON]]
    * [[https://docs.apiary.io/api_101/uri-templates/|URI Templates]]
    * [[https://docs.apiary.io/api_101/json-schema/|JSON Schema]]
  * Les spécifications :
    * [[https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md|API Blueprint]]
    * [[https://github.com/apiaryio/mson|MSON]]

=== Notes ===
  * Pour pouvoir gérer différente version de //nodejs// (et //npm//), il faut utiliser : **//nvm//**
  * Installer //npm// globallement avec //nvm// : ## n=$(which node);n=${n%/bin/node}; chmod -R 755 $n/bin/*; sudo cp -r $n/{bin,lib,share} /usr/local ##
  * Pour que //Protagonist// fonctionne, il faut bien compiler tous les paquets avec la même version de //Node//.
  * Comma separated URI parameter : https://github.com/apiaryio/api-blueprint/issues/120

===== Swagger =====
Site principal : [[http://swagger.io/specification/|Swagger]] : v2.0 (2014-09-08) [Licence Apache, v2.0]
Ancien, mais toujours actif. Syntaxe YAML. Editeur et doc utilise nodejs. L'écosystème semble moins développer que les précédents. Le générateur de SDK est en Java...
=== Ressources ===
  * [[https://github.com/swagger-api/swagger-editor|Swagger-Editor]] : interface web (utilise Node.js)
  * [[https://github.com/swagger-api/swagger-ui|Swagger-ui]] : interface de consultation de la doc Swagger (HTML 5). [Licence Apache, v2.0]

===== Initialisation d'un projet de doc avec Apiblueprint =====
  - Installer le gestionnaire de version de node : ## nvm ##
  - Installer la version 0.12.8 : ##nvm install 0.12.8##
  - Basculer sur la version de node 0.12.8 : ##nvm use 0.12.8##
  - Avec npm initialiser un projet de doc : ##npm init##
  - Puis installer les paquets :
    * aglio : pour générer la doc au format HTML.
    * drakov : serveur qui 'mocke' une api en fonction de la doc APIblueprint.
    * dredd : pour tester la doc vis à vis de l'api développée. Permet de vérifier la consistance de la doc vis à vis de l'API réelle.
    * hercule : permet de réaliser la transclusion de contenu présent dans différents fichiers.

=== Aglio (node : v0.12.8) ===
Pour simplifier, on peut rajouter ces commandes dans la partie //scripts// du fichier //package.json//, avec les entrées :
<code>
"aglio-server": "./node_modules/.bin/aglio -i mon-api.apib --theme-full-width --theme-variables flatly -s",
"aglio-convert": "./node_modules/.bin/aglio -i mon-api.apib --theme-full-width --theme-variables flatly -o mon-api.html"
</code>

=== Drakov (node : v0.12.8) ===
Serveur de mock de l'API.
Ajouter dans la partie //scripts// du fichier //package.json// : 
<code>
"drakov": "./node_modules/.bin/drakov -f mon-api.apib"
</code>

=== Dredd (node : v0.12.8) ===
  * Pour initialiser //Dredd// et créer le fichier de config //dredd.yml//, lancer la commande : ##./node_modules/.bin/dredd init##
  * Pour lancer les tests avec Dredd : ##./node_modules/.bin/dredd##
  * Pour simplifier, on peut rajouter ces commandes dans la partie //scripts// de //package.json// :
<code>
"dredd": "./node_modules/.bin/dredd"
</code>

On pourra ensuite utiliser les commandes :
  * ## npm run dredd init ##
  * ## npm run dredd ##

===Hercule  (node v0.12.8) ===
Permet de découper une document Markdown en plusieurs sous partie.
  * Pour simplifier, on peut rajouter une commande dans la partie //scripts// de //package.json// :
<code>
"hercule": "./node_modules/.bin/hercule mon-api.src.apib -o mon-api.apib"
</code>

=== Gulp  (node v0.12.8) ===
Permet d'automatiser le fonctionnement des modules ci-dessus : aglio, dredd et hercule.
<code javascript>
var gulp = require('gulp');
var plumber = require('gulp-plumber');
var rename = require("gulp-rename");
var es = require('event-stream');
var hercule = require('hercule');
var dredd = require('dredd');
var exec = require('child_process').exec;

gulp.task('default', ['startWatcher', 'startAglioServer']);

gulp.task('startAglioServer', function() {
  exec('./node_modules/.bin/aglio -i mon-api.apib --theme-full-width --theme-variables flatly -s', function (error, stdout, stderr) {
    console.log('Stdout: ' + stdout);
    console.log('Stderr: ' + stderr);
    if (error !== null) {
      console.log('Exec error: ' + error);
    }
  });
});

gulp.task('startWatcher', function() {
  var watcher = gulp.watch('mon-api.src.apib', ['doHercule']);
  var watcherDest = gulp.watch('mon-api.apib', ['doDredd']);

  watcher.on('change', function(event) {
    console.log('File ' + event.path + ' was ' + event.type + ', running tasks...');
  });
});

gulp.task('doHercule', function() {
  function transclude() {
    // you're going to receive Vinyl files as chunks
    function transform(file, cb) {
      hercule.transcludeString(file.contents.toString(), function(output) {
        file.contents = new Buffer(output);
      });
      cb(null, file);
    }
    return es.map(transform);
  };

  gulp.src('mon-api.src.apib')
    .pipe(plumber())
    .pipe(transclude())
    .pipe(rename('mon-api.apib'))
    .pipe(gulp.dest('./'));
});

gulp.task('doDredd', function() {
  var dreddConfig = {
    server: 'http://api.mon-site.org/mon-api/v1', // your URL to API endpoint the tests will run against
    options: {
      'path': 'mon-api.apib',       // Required Array if Strings; filepaths to API Blueprint files, can use glob wildcards
      'dry-run': false, // Boolean, do not run any real HTTP transaction
      'names': false,   // Boolean, Print Transaction names and finish, similar to dry-run
      'level': 'verbose', // String, log-level (info, silly, debug, verbose, ...)
      'silent': false, // Boolean, Silences all logging output
      'only': [],      // Array of Strings, run only transaction that match these names
      'header': [],    // Array of Strings, these strings are then added as headers (key:value) to every transaction
      'user': null,    // String, Basic Auth credentials in the form username:password
      'hookfiles': [], // Array of Strings, filepaths to files containing hooks (can use glob wildcards)
      //'reporter': ['dot', 'html'], // Array of possible reporters, see folder src/reporters
      //'output': [],     // Array of Strings, filepaths to files used for output of file-based reporters
      'inline-errors': false, // Boolean, If failures/errors are display immediately in Dredd run
      'color': true,
      'timestamp': false
    }
    //'emitter': EventEmitterInstance, // optional - listen to test progress, your own instance of EventEmitter
    //'hooksData': {
    //  'pathToHook' : ''
    //}
  };
  var dredd = new dredd(dreddConfig);
  dredd.run(function (err, stats) {
    if (err) {
      console.log(err);
    }
  });
});
</code>