jsonapi2raml

Utility used to generate RAML v1.0 Documentation for REST APIs that follow the JSON-API spec.

Installation

npm install jsonapi2raml

Demo

CLI

Usage

jsonapi2raml <file-name> <file-output> [options]

Note: To use jsonapi2raml from CLI you need to install it globally.

Options	Description
<payload>	The name of the file containing the payload which jsonapi2raml will parse to generate the RAML Documenation. More info about the structure of this file below.
<output>	The name of the file or directory where jsonapi2raml will be generating the RAML documentation in.
version	Shows version.

API

You can use the API directly:

const jsonapi2raml = require('jsonapi2raml')
jsonapi2raml.generate({
  payload: [...],
  output: 'path/to/raml',
  generator: jsonapi2raml.generators.singleFile
})

Generators

A Generator is a function that will be invoked by jsonapi2raml once the parsing has been done. This function will be invoked with the following info:

• Output file name.
• Generated RAML objects.

Example of a Generator argument:

{
  output: 'path/to/raml',
  assets: {
    // The names of RAML Types common to all REST APIs which follow the JSON-API
    // Spec. More info in '/src/libs/asset-names.js'
    names: {..},
    raml: {
      // RAML Endpoints.
      endpoints: {..},
      // RAML Trait Representational objects common to all REST APIs which
      // follow the JSON-API Spec
      traits: {..},
      // RAML Resource Types Representational objects common to all REST APIs
      // which follow the JSON-API Spec
      resourceTypes: {..},
      types: {
        // RAML Types Representational objects common to all REST APIs which
        // follow the JSON-API Spec
        generic: {..},
        // RAML Types Representational objects related to the provided JSON-API
        // Resources
        payload: {..}
      }
    }
  }
}

Default Generators

jsonapi2raml comes with the following generators:

Single File

Generates the RAML Documentation in a single file.

const jsonapi2raml = require('jsonapi2raml')
jsonapi2raml.generate({
  payload: [...],
  output: 'path/to/raml',
  generator: jsonapi2raml.generators.singleFile
})

Payload Structure

For jsonapi2raml to generate the RAML Documentation of a REST API that follow the JSON-API spec all it needs is info about the JSON-API Resources.

Example of a Payload file:

[{
  "type": "user",
  "attributes": {
    "name": {
      "type": "string",
      "maxLength": 10,
      "pattern": "/[a-zA-Z]/"
    },
    "age": "integer"
  },
  "relationships": {
    "token": {
      "data": {
        "type": "token"
      }
    }
  }
}, {
  "type": "token",
  "attributes": {
    "value": "string",
    "created": "datetime"
  }
}]

Note: The value of an attribute should be a RAML Built-in Type.

Acknowledgments

Thanks for your feedback & support!

• gdebat
• giulio90
• isaacchircop