apiaryio
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 protagonistProtagonist 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,
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) |
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 204Would 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 installWhile iterating on the package, you can use npm run build to compile
Protagonist:
$ npm run build
$ npm testProtagonist is built using node-gyp, you can consult their documentation for further information on the build system.
License
MIT License. See the LICENSE file.