Snow Crash parser harness
C++ Python API Blueprint C Emacs Lisp Batchfile
tjanc Merge pull request #565 from apiaryio/kylef/refractfilter-yamlless
Script refract-filter.py to work without pyyaml on JSON input
Latest commit cd11dc5 Jul 19, 2018
Permalink
Failed to load latest commit information.
.circleci chore(ci): Test on Clang 4 and 5 Jun 19, 2018
drafter.xcodeproj chore: Add newer files to xcode build system (still working on fixing… Mar 6, 2018
drafter.xcworkspace Correct drafter xcodeproj file location Aug 4, 2015
ext (fix/json-schema) "fixed" modifier inheritance Jul 10, 2018
features (json-schema) full implementation Jul 10, 2018
src Merge pull request #552 from apiaryio/tjanc/schema-object Jul 10, 2018
test Merge pull request #552 from apiaryio/tjanc/schema-object Jul 10, 2018
tools fix(refract-filter): Restore script to work without pyyaml Jul 18, 2018
.clang-format chore(clang-format): Copied configuration from SC Aug 11, 2017
.gitattributes Support for MSVS2015 Feb 22, 2016
.gitignore (util) trivial logger, enabled via cmd line option Feb 19, 2018
.gitmodules fix: Catch repository was moved to catch org May 25, 2018
ARCHITECTURE.md Update ARCHITECTURE.md Jul 10, 2017
CHANGELOG.md Update chanegelog Feb 8, 2018
Dockerfile fix(docker): Use base GCC image Aug 18, 2017
Gemfile * backport integration tests Feb 13, 2015
Gemfile.lock Partial MSON impl Oct 27, 2015
LICENSE Initial commit Feb 9, 2015
Makefile refactor: implemented interfaces for Element content Jan 24, 2018
README.md fix headline Jul 12, 2017
appveyor.yml Updated appveyor and Changelog Apr 30, 2016
common.gypi feat: compile with -O3 Sep 11, 2017
configure chore: Polish mono repo build system Aug 29, 2017
drafter.gyp (fix/json-schema) "fixed" modifier inheritance Jul 10, 2018
vcbuild.bat refactor: implemented interfaces for Element content Jan 24, 2018

README.md

logo

Drafter Circle CI Build status

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:

  • API Elements Parse Result: Parse Result is defined in API Elements according to Parse Result Namespace.
  • Normal AST Parse Result: Parse Result defined by the API Blueprint AST Parse Result. The AST is deprecated and only available in the Drafter command line tool.

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

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.

Usage

Drafter is both a library and a command line tool.

Command line tool

The command line tool allows you to parse a blueprint and/or check the validity of a blueprint.

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

C/C++ API

Please refer to drafter.h for the full API documentation. See Drafter bindings for using the library in other languages.

Parsing a blueprint to a JSON or YAML string

The drafter_parse_blueprint_to takes a source blueprint and returns the given blueprint parsed and serialized as API Elements in YAML or JSON.

int drafter_parse_blueprint_to(const char* source, char ** out, const drafter_options options);
#include <drafter/drafter.h>

const char* blueprint =
  "# My API\n"
  "## GET /message\n"
  "+ Response 200 (text/plain)\n"
  "\n"
  "      Hello World!\n";

drafter_options options;
options.format = DRAFTER_SERIALIZE_JSON;
options.sourcemap = true;

char* result = NULL;
if (drafter_parse_blueprint_to(blueprint, &result, options) == 0) {
    printf("%s\n", result);
    free(result);
}

Checking the validity of a blueprint

The drafter_check_blueprint function allows checking the validity of a blueprint. This function will return a drafter_result when the blueprint produces warnings and/or errors. With a drafter_result, the drafter_serialize function can be used to serialized the result as API Elements in YAML or JSON.

drafter_result* drafter_check_blueprint(const char* source);
#include <drafter/drafter.h>

const char* blueprint =
  "# My API\n"
  "## GET /message\n"
  "+ Response 200 (text/plain)\n"
  "\n"
  "      Hello World!\n";

drafter_result* result = drafter_check_blueprint(blueprint);
if (result) {
    // Serialize the result to print the warnings/errors

    drafter_options options;
    options.format = DRAFTER_SERIALIZE_JSON;
    options.sourcemap = true;

    char* out = drafter_serialize(result, options);
    printf("The blueprint produces warnings or errors:\n\n%s\n", out);
    free(out);

    drafter_free_result(result);
} else {
    printf("The given blueprint was valid.\n");
}

Build

Compiler Support

Compiler Minimum Supported Version
Clang 4.0
GCC 5.3
MSVC++ 2015
  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:

CLI Wrapper

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.