Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Join the chat at

generator-ramlapi is a generator for Yeoman that generates a project scaffold for API development in RAML and JSON Schema.


  • RAML validation
  • RAML HTML document generation (via RAML2HTML) with improved HTML templates
  • JSON Schema validation
  • Example validation against JSON Schema

See also:


Build Status Dependency Status Codacy Badge

Getting Started:

Installing Dependencies

Install NodeJS. On OSX, installation via NVM and/or Homebrew is highly recommended.

Update NPM. Depending on your installation, you may need to use sudo for the following commands.

npm install -g npm

Install Yeoman, Gulp and generator-ramlapi:

npm install -g yo gulp generator-ramlapi

Beginning a project

Create a directory for your RAML API project and cd into it.

Run the generator like this:

yo ramlapi

The generator will ask you a number of questions. Answer these as completely as you can, but all can be changed later if need be.

After the questions, the generator will install the NPM dependencies for your project.


To run the validation and build HTML docs, simply run the command:


Validates the JSON Schema, RAML, and produces documentation in the public/ directory.

Project Structure

  • *.raml: files located in the root directory are documented.
  • raml/: RAML fragment files referenced by the primary RAML.
  • schema/: JSON Schema files referenced in RAML files (or fragments).
  • examples/: JSON example files for the JSON Schema.
  • public/: a folder suitable to publish to a GitHub project page with generated documentation.
  • templates/: contains the RAML2HTML templates that are used instead of the default templates.

RAML Notes

RAML files should not include JSON Schema directly, but should instead use !include to include them from the schema/ directory. This isn't essential - just a best practice.

raml2html is used to generate the documentation HTML.

Schema Notes

Schema files are expected to be stored in the schema/ directory.

Example files are stored in the examples/ directory.

Example files that are included in a RAML media type section with a schema are validated against that schema.

Generator improvements to come

  1. scaffold the github page
  2. gulp-watch support




A Yeoman Generator to produce RAML API projects







No packages published