!logo

Protagonist - API Blueprint Parser for Node.js


Protagonist is a Node.js wrapper for the
Drafter, an API Blueprint parser. API
Blueprint is a language for describing web APIs.

Install

NOTE: *For general use we recommend that you use the Drafter
NPM package instead of Protagonist
directly as Protagonist needs to be compiled which may not be possible in every
situation.*

Protagonist can be installed via the Protagonist npm
package by
npm or yarn.

``sh
$ npm install protagonist


or


$ yarn install protagonist
`

Protagonist uses the
node-gyp build tool which
requires Python 2.7 (3.x is not supported) along with a compiler and other
build tools. Take a look at their installation steps for
Linux,
macOS, and
Windows.

Usage

Protagonist offers the ability to both validate, and parse an API Blueprint.
It offers the following APIs:

- validate(source, options)
- validateSync(source, options)
- parse(source, options)
- parseSync(source, options)

NOTE: *It is not recommended to use the synchronous APIs as they can block
the Node.JS event loop.*




$3

You can validate an API Blueprint to determine if the source is a valid
document. The parse result will contain any errors or warnings that the
document would emit during parsing.

`js
const protagonist = require('protagonist');

const parseResult = await protagonist.parse('# My API');
console.log(JSON.stringify(parseResult, null, 2));
`

or by using Promises:

`js
const protagonist = require('protagonist');

protagonist.validate('# My API')
.then((parseResult) => {
console.log(JSON.stringify(parseResult, null, 2));
})
.catch((error) => {
console.error(error);
});
`

See the parse result section below for more information about
the structure of the parse result.


#### Synchronous API

`js
const protagonist = require('protagonist');
const parseResult = protagonist.validateSync('# My API');
`

#### Validation Options

Options can be passed to the parser as an optional second argument to both the asynchronous and synchronous interfaces:

`js
const protagonist = require('protagonist');

const options = {
requireBlueprintName: true,
};
const parseResult = await protagonist.validate('# My API', options);
`

The available options are:

Name | Description
---------------------- | ----------------------------------------------------------
requireBlueprintName | Require parsed blueprints have a title (default: false)




$3

You can parse an API Blueprint with async/await:

`js
const protagonist = require('protagonist');

const parseResult = await protagonist.parse('# My API');
console.log(JSON.stringify(parseResult, null, 2));
`

or by using Promises:

`js
const protagonist = require('protagonist');

protagonist.parse('# My API')
.then((parseResult) => {
console.log(JSON.stringify(parseResult, null, 2));
})
.catch((error) => {
console.error(error);
});
`

See the parse result section below for more information about
the structure of the parse result.


#### Synchronous API

`js
const parseResult = protagonist.parseSync('# My API');
`

#### Parsing Options

Options can be passed to the parser as an optional second argument to both the asynchronous and synchronous interfaces:

`js
const options = {
generateSourceMap: true,
generateMessageBody: true,
generateMessageBodySchema: true,
};
const parseResult = await protagonist.parse('# My API', options);
`

The available options are:

Name | Description
--------------------------- | ----------------------------------------------------------
requireBlueprintName | Require parsed blueprints have a title (default: false)
generateSourceMap | Enable sourcemap generation (default: false)
generateMessageBody | Enable generation of messageBody from MSON (default: true)
generateMessageBodySchema | Enable generation of messageBodySchema from MSON (default: true)




$3

The format of the parse result is an API Elements
structure, there is also API Elements:
JS which contains tooling to
handle this format in JavaScript. It is recommended to use the provided API
Elements tooling to prevent any tight
coupling
between your tool and a parse result.

As an example, parsing the following API Blueprint:

`apib


GET /


+ Response 204
`

Would result in the following API Elements Parse
Result:

`json
{
"element": "parseResult",
"content": [
{
"element": "category",
"meta": {
"classes": {
"element": "array",
"content": [
{
"element": "string",
"content": "api"
}
]
},
"title": {
"element": "string",
"content": ""
}
},
"content": [
{
"element": "resource",
"meta": {
"title": {
"element": "string",
"content": ""
}
},
"attributes": {
"href": {
"element": "string",
"content": "/"
}
},
"content": [
{
"element": "transition",
"meta": {
"title": {
"element": "string",
"content": ""
}
},
"content": [
{
"element": "httpTransaction",
"content": [
{
"element": "httpRequest",
"attributes": {
"method": {
"element": "string",
"content": "GET"
}
},
"content": []
},
{
"element": "httpResponse",
"attributes": {
"statusCode": {
"element": "string",
"content": "204"
}
},
"content": []
}
]
}
]
}
]
}
]
}
]
}
`

Developing Protagonist

You can use the following steps to build and test Protagonist.

`sh
$ git clone --recursive https://github.com/apiaryio/protagonist.git
$ cd protagonist
$ npm install
`

While iterating on the package, you can use npm run build to compile
Protagonist:

`sh
$ npm run build
$ npm test
``

Protagonist is built using node-gyp, you
can consult their documentation for further information on the build system.

License

MIT License. See the LICENSE file.