Menu

Subscribe

gulp-raml

I just built my first gulp plugin: gulp-raml.

Now I know, I know... you're not supposed to write gulp plugins for everything like it's Grunt, but I think this one might actually be useful :)

But first, a short introduction:

RAML

RAML is a .yml based specification language for REST API:s (RESTful API Modeling Language). You can read more about it at raml.org. Basically it helps you specify your traits (like paged, secured etc), schemas, responses, resources and verbs. This can then be used to generate documentation, a stub api, tests etc.

Gulp

TL;DR

gulp is hipster Grunt

Seriously

Gulp is described as "The streaming build system". It is basically a task runner for node. The main differences from Grunt are:

  • It uses streams that are piped from task to task instead of reading the same files over, and over again
  • You specify your tasks using JavaScript instead of declarative JSON
  • Plugins are frowned upon

The benefits of this is that it is easier to setup, assuming you're a programmer and that the tasks you specify aren't hard linked to specific plugins.

gulp-raml

When trying to use RAML JavaScript Parser throgh gulp to continously validate my RAML, I found it a bit cumbersome. So I wrote a plugin. At the moment, all it does is validate .raml files and report the results in the console. The next step though is to add documentation capabilities that run the results through .handlebars files to output HTML. This is why I decided to basically rip off the structure of the gulp-jshint plugin.

Give it a try

The plugin is available on GitHub @ https://github.com/JohanObrink/gulp-raml. You can add it to your projects using:

	npm install gulp-raml

Then just add a task to your gulp file

	var raml = require('gulp-raml');
	var gulp = require('gulp');
	
	gulp.task('raml', function() {
		gulp.src('./raml/*.raml')
			.pipe(raml())
			.pipe(raml.reporter('default'));
	});

If you want gulp to break on parse errors (like in a CI build), just pipe it to fail:

	stuff
		.pipe(raml())
		.pipe(raml.reporter('default'))
		.pipe(raml.reporter('fail'))

gl hf