jsonapi2raml
v0.2.7
Published
Generates RAML for REST APIs that follow JSON-API spec.
Downloads
13
Maintainers
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 Resource
s.
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!