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
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:
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
*.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 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 files are expected to be stored in the
Example files are stored in the
Example files that are included in a RAML media type section with a schema are validated against that schema.
Generator improvements to come
- scaffold the github page
- gulp-watch support