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.

$ 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.

Validating an API Blueprint

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.

const protagonist = require('protagonist');

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

or by using Promises:

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

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:

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)

Parsing an API Blueprint

You can parse an API Blueprint with async/await:

const protagonist = require('protagonist');

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

or by using Promises:

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

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:

const options = {
  generateSourceMap: 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)

Parse Result

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:

# GET /
+ Response 204

Would result in the following API Elements Parse
Result:

{
  "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.

$ 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:

$ 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.