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.

Status

• Format 1A8 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 "SerializeAST.h" // Blueprint 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::WrapBlueprint(ast.node), 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, &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 
_version: 3.0
metadata:
name: "My API"
 ...

Refer to AST Serialization Media Types for the details on serialized media types. 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)

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.