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 AST: AST is defined in Refract elements according to Parse Result Namespace
Normal AST: AST defined by the API Blueprint AST Parse Result.

By default, Drafter assumes the Refract AST.

Both the types of AST 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 "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, 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: "category"
meta:
  classes:
    - "api"
  title: "My API"
 ...

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

Build

Clone the repo + fetch the submodules:

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

Build & test Drafter:
```
$ ./configure
$ make test
```
To include integration tests (using Cucumber) use the --include-integration-tests flag:
```
$ ./configure --include-integration-tests
$ make test
```