Drafter

Snowcrash parser harness

API Blueprint Parser

Drafter is complex builder of API Blueprint. Internally it uses Snowcrash library, reference API Blueprint parser.

API Blueprint is Web API documentation language. You can find API Blueprint documentation on the API Blueprint site.

Additionally Drafter provide set of Wrappers for serialization, of parsing result, via SOS library into JSON and YAML format.

Drafter also provides the user ability to select the type of the output. There are two possible values:

• Refract Parse Result: Parse Result is defined in Refract elements according to Parse Result Namespace
• Normal AST Parse Result: Parse Result defined by the API Blueprint AST Parse Result.

By default, Drafter assumes the Refract Parse Result.

Both the types of Parse Results are available in two different serialization formats, YAML and JSON. YAML is the default for the CLI.

Status

• Format 1A9 fully implemented

Install

OS X using Homebrew:

$ brew install --HEAD \
  https://raw.github.com/apiaryio/drafter/master/tools/homebrew/drafter.rb

AUR package for Arch Linux.

Other systems refer to build notes.

Use

C++ library

#include "drafter.h"         // Blueprint Parser
#include "SerializeResult.h" // Result Wrapper for serialization
#include "sosJSON.h"         // Serializer

mdp::ByteBuffer blueprint = R"(
# My API
## GET /message
+ Response 200 (text/plain)

        Hello World!
)";

// Blueprint parsing
snowcrash::ParseResult<snowcrash::Blueprint> ast;
drafter::ParseBlueprint(blueprint, 0, ast);

std::cout << "API Name: " << ast.node.name << std::endl;

// Serialization to JSON format
sos::SerializeJSON serializer;
serializer.process(drafter::WrapResult(ast.node, drafter::WrapperOptions(drafter::RefractASTType)), std::cout);

C-interface

For purpose of bindings to other languages Drafter provides very simple C-interface.

#include "cdrafter.h"

const char* source = "# My API\n## GET /message\n + Response 200 (text/plain)\n\n        Hello World\n";
char *result = NULL;
int ret = drafter_c_parse(source, 0, DRAFTER_REFRACT_AST_TYPE, &result);

printf("Result: %s\n", ret == 0 ? "OK" : "ERROR");
printf("Serialized JSON result:\n%s\n", result);

free(result); /* we MUST release allocted memory for result */

Refer to Blueprint.h for the details about the Snow Crash AST and BlueprintSourcemap.h for details about Source Maps tree. See Drafter bindings for using the library in other languages.

Command line tool

$ cat << 'EOF' > blueprint.apib
# My API
## GET /message
+ Response 200 (text/plain)

        Hello World!
EOF

$ drafter blueprint.apib
element: "parseResult"
content:
  -
    element: "category"
    meta:
      classes:
        - "api"
      title: "My API"
...

See parse feature for the details on using the drafter command line tool.

Build

1. Clone the repo + fetch the submodules:

   $ git clone --recursive git://github.com/apiaryio/drafter.git
   $ cd drafter

2. Build & test Drafter:

   $ ./configure
   $ make test

   To include integration tests (using Cucumber) use the --include-integration-tests flag:

   $ ./configure --include-integration-tests
   $ make test

We love Windows too! Please refer to Building on Windows.

Drafter command line tool

1. Build drafter:

   $ make drafter

2. Install & use drafter:

   $ sudo make install
   $ drafter --help

Bindings

Drafter bindings in other languages:

• Protagonist (Node.js)
• RedSnow (Ruby)

CLI Wrapper

• Drafter-php (PHP)

drafter.js

Note: drafter.js is work in progress, use only for experimental purposes

drafter.js is a pure JavaScript version of the drafter library. It exposes a single parse function which takes an API Blueprint string and options as input and returns the parse result. It is built from the C++ sources using emscripten.

It can be downloaded from the releases page or installed via npm install drafter.js.

// Web browser
<script src="./drafter.js"></script>
<script src="./drafter.js.mem"></script>
// Node.js
var drafter = require('drafter.js');

// Example usage once loaded via one of the methods above:
try {
  var res = drafter.parse('# API Blueprint...', {exportSourcemap: true});
  console.log(res);
} catch (err) {
  console.log(err);
}

Supported options:

• exportSourcemap: Set to export sourcemap information.
• json: Set to false to disable parsing of the JSON data. You will instead get a JSON string as the result.
• requireBlueprintName: Set to generate an error if the blueprint is missing a title.
• type: Either refract (default) or ast.

drafter.js can serve as drop in replacement for protagonist, it supports the same API. So stuff like

try {
  var protagonist = require('protagonist');
}
catch (e) {
  console.log("protagonist not found, using drafter.js.");
  var protagonist = require('drafter.js');
}

protagonist.parse(data, options, function(err, result) {
  if (err) {
    console.log(JOSN.stringify(err));
  }
  console.log(JSON.stringify(data));
});

is possible. Protagonist parseSync function is available too.

Build drafter.js

*Unfortunately building drafter.js works only on a nix environment at the moment.

1. Building is easy using Docker.

2. Build

   $ docker pull "apiaryio/base-emscripten-dev"
   $ docker run -v $(pwd):/src -t apiaryio/base-emscripten-dev emcc/emcbuild.sh

3. Check out the ./emcc/test-drafter.js and ./emcc/test.html files for example usage. You can also use npm install and then npm test to run the tests.

The resulting stand-alone library drafter.js is in the ./emcc directory. Don't forget to serve the drafter.js.mem file as it is required by drafter.js. There is also a single-file version in drafter.nomem.js that can be used, but it may take longer to load in a web browser environment.

To get a debug version or version enabled to be used with emrun run the emcbuild.sh script it with -d or -e respectively.

Squeeze the size

If you want to squeeze the size to a minimum install uglify-js and try running emcbuild.sh -u, this will use uglify-js with compression, beware that this might cause some errors, if you encounter them try drafter.js without it to verify that it is caused by uglify-js and report it please.

Contribute

Fork & Pull Request

If you want to create a binding for Drafter please refer to the Writing a Binding article.

License

MIT License. See the LICENSE file.