Package Exports

jsonapi2raml

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (jsonapi2raml) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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!