Clone this repository:

Install dependencies:

For external reasons, an up-to-date blueprint compilation is required to be checked into repository. It is stored in apiary.apib file. In order to compile and validate apiary.apib, run following:

After successful blueprint compilation, a tiny validation tool is run. Issues, if any, will be printed in console.

We use Hercule tool to compile apiary.apib from the source files. It introduces the concept of transclusion, which roughly means including one document in another, at least in our simple case.

To find out more about this tool, visit https://github.com/jamesramsay/hercule.

Final blueprint is built from section subdocuments which reside in the sections/ directory. The input.apib defines how that document is composed, hence don’t forget to update that file when contributing a new section. Section subdocuments are transcluded with :()[sections/<section-name>.apib] expressions. For example, expression :()[sections/space.apib] will transclude content of sections/space.apib file.

Response fixtures can be imported from spec/fixtures directory of the ribose-ruby project. They are transcluded with :()[fixture:fixture-file-name] expression. For example, :()[fixture:spaces.json] will resolve to spec/fixtures/spaces.json in ribose-ruby project.

Under the hood, Git submodules are involved. The ribose-ruby project is added as a submodule in fixtures directory. Run git submodule update to grab the freshest content, if necessary.

If you want to read more about submodules, Git Book contains an excellent chapter on this topic: https://git-scm.com/book/en/v2/Git-Tools-Submodules

HTML comments can be used in document, either in input.apib or in any section. They are removed at blueprint compilation.