Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
P

protagonist

> 编程语言
Open source

Protagonist is Node.js wrapper for the API Blueprint parser

358 stars0 likes0 views
WebsiteGitHub

About

Protagonist is Node.js wrapper for the API Blueprint parser

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.

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

javascript
const protagonist = require('protagonist');

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

or by using Promises:

javascript
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

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

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

javascript
const protagonist = require('protagonist');

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

or by using Promises:

javascript
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

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

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

apib
# GET /
+ Response 204

Would result in the following API Elements Parse Result:

…

Developing Protagonist

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

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

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

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

C++api-blueprintnodejs-librarynodejs-modules

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言