Skip to content

Instantly share code, notes, and snippets.

@iki
Last active January 18, 2019 16:38
  • Star 8 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
Save iki/784ddd5ab33c1e1b726b to your computer and use it in GitHub Desktop.
generating API documentation from RAML specification using raml2html in gulp
'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'));
});
{
"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"
}
}
@lukaskostial
Copy link

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 )

@iki
Copy link
Author

iki commented Nov 18, 2015

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

@javafun
Copy link

javafun commented Jan 10, 2018

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

@Bernardoow
Copy link

Bernardoow commented Jan 18, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment