generating API documentation from RAML specification using raml2html in gulp

gulpfile.js

'use strict';

var gulp = require('gulp');
var path = require('path');

var CWD = path.resolve('.');
var API_SPEC = path.resolve(CWD, '../api/api.raml');
var API_DEST = path.resolve(CWD, '../server/static/docs/api');
var API_HTML = 'index.html';

function raml2html(options) {
  var gutil = require('gulp-util');
  var through = require('through2');
  var raml2html = require('raml2html');

  var simplifyMark = function(mark) {
    if (mark) mark.buffer = mark.buffer.split('\n', mark.line + 1)[mark.line].trim();
  }

  options = options || {};

  switch (options.type) {
    case 'json':
      var Q = require('q');
      options.config = {processRamlObj: function(raml) { return Q.fcall(function() {
        return JSON.stringify(raml, options.replacer, 'indent' in options ? options.indent : 2);
      })}};
      break;
    case 'yaml':
      var Q = require('q');
      var yaml = require('js-yaml');
      options.config = {processRamlObj: function(raml) { return Q.fcall(function() {
        return yaml.safeDump(raml, {skipInvalid: true, indent: options.indent, flowLevel: options.flowLevel});
      })}};
      break;
    default:
      options.type = 'html';
      options.config = options.config || raml2html.getDefaultConfig(options.template, options.templatePath);
  }

  var stream = through.obj(function(file, enc, done) {
    var fail = function(message) {
      done(new gutil.PluginError('raml2html', message));
    };
    if (file.isBuffer()) {
      var cwd = process.cwd();
      process.chdir(path.resolve(path.dirname(file.path)));
      raml2html.render(file.contents, options.config).then(
        function(output) {
          process.chdir(cwd);
          stream.push(new gutil.File({
            base: file.base,
            cwd: file.cwd,
            path: gutil.replaceExtension(file.path, options.extension || '.' + options.type),
            contents: new Buffer(output)
          }));
          done();
        },
        function(error) {
          process.chdir(cwd);
          simplifyMark(error.context_mark);
          simplifyMark(error.problem_mark);
          process.nextTick(function() {
            fail(JSON.stringify(error, null, 2));
          });
        });
    }
    else if (file.isStream()) fail('Streams are not supported: ' + file.inspect());
    else if (file.isNull()) fail('Input file is null: ' + file.inspect());
  });

  return stream;
}

function logErrorAndQuit(err) {
  console.error(err.toString());
  this.emit('end');
}

gulp.task('apidoc', function() {
  var rename = require('gulp-rename');

  return gulp.src(API_SPEC)
    .pipe(raml2html())
    .on('error', logErrorAndQuit)
    .pipe(rename(API_HTML))
    .pipe(gulp.dest(API_DEST));
});

gulp.task('apijson', function() {
  return gulp.src(API_SPEC)
    .pipe(raml2html({type: 'json'}))
    .on('error', logErrorAndQuit)
    .pipe(gulp.dest(API_DEST));
});

gulp.task('apiyaml', function() {
  return gulp.src(API_SPEC)
    .pipe(raml2html({type: 'yaml'}))
    .on('error', logErrorAndQuit)
    .pipe(gulp.dest(API_DEST));
});

gulp.task('apilint', function() {
  var raml = require('gulp-raml');
  // Fails on Windows, until https://github.com/JohanObrink/gulp-raml/issues/4 is resolved.

  return gulp.src(API_SPEC)
    .pipe(raml())
    .pipe(raml.reporter('default'))
    .pipe(raml.reporter('fail'));
});

package.json

{
  "name": "my-project",
  "version": "0.0.0",
  "devDependencies": {
    "gulp": "3.9.0",
    "gulp-rename": "^1.2.2",
    "gulp-util": "^3.0.7",
    "js-yaml": "^3.4.3",
    "q": "^1.4.1",
    "raml2html": "^2.1.2",
    "through2": "^2.0.0"
  },
  "engines": {
    "node": ">=0.10.0"
  }
}

addresses gulp-raml2html issues #6 and #12
basically allows you to always use latest raml2html version

Hi Iki,

Just a small issue with raml2html.render() call - it takes just first two params and returns a promise so it should be like this:

raml2html.render(file.contents, options.config).then( successFn, failureFn )

@lukaskostial thanks, updated to work w/ current raml2html 2.1.2 - cc @kevinrenskers

Hi @iki, can you provide an update gulpfile that supports RAML 1.0?

To use in RAML 1.0 I change the line 38 to options.config = options.config || raml2html.getDefaultConfig(options.template, options.templatePath); and line 48 to raml2html.render(file.path, options.config).then

Gist to my updated