Working with multiple API Blueprint files

gistfile1.md

Working with multiple blueprint files

This document describes 4 different solutions to work APIs that consist of multiple blueprint files. Every of this solution work with all Apiary.io features but editing. To edit a blueprint you have to do it outside of Apiary as Apiary editor does not support working with multiple files. In other words if you are using one of the solutions below avoid editing the blueprint in Apiary.

1. Hercule

Hercule is a CLI tool written in Node.js – available as an NPM package. It uses markdown referencing and linking syntax to transclude other files into a blueprint file. This solution is universal and would work with any Markdown files not just API Blueprint.

The major benefit – unlike any other solutions here – is also that the references are rendered as HTML links in any Markdown editor so the result is HTML that can be browsed!

The syntax used in Hercule is the closest to the official API Blueprint referencing syntax as proposed at apiaryio/api-blueprint#8 and apiaryio/api-blueprint#20.

Example syntax:

# Gist Fox API

# Group Gist

:[Gist](blueprint/gist.apib)

:[Gists](blueprint/gists.apib)

Source:

https://github.com/jamesramsay/hercule

2. Aglio

Aglio is very popular static-site renderer for API Blueprint. It came with its very own transclusion syntax utilizing HTML comments. As a downside, if you render this as a plain Markdown (e.g. on GitHub) the references will disapear.

Example syntax:

# Gist Fox API

# Group Gist

<!-- include(blueprint/gist.apib) -->

<!-- include(blueprint/gists.apib) -->

Source:

https://github.com/danielgtaylor/aglio

Example:

https://github.com/the-grid/apidocs/

3. Grunt task

A node.js grunt task that concatenates files into the apiary.apib . It can also push – publish – the blueprint into Apiary.

Source:

https://github.com/dac09/grunt-apiary-blueprint

4. Apiary manifest

Alpha-quality tool developed by Apiary. Working only with Apiary GitHub integration. Works similarly to Grunt task however you have to explicitly enumerate files to be concatenate in the apiary.manifest file. This manifest file must be in the root of your repository. It is recommended to NOT use apiary.apib file with this solution.

Syntax (apiary.manifest) :

api_intro.apib
blueprint/gist.apib
blueprint/gists.apib

Example:

https://github.com/zdne/apiary-manifest

---

Roundup

Personally I endorse the Hercule and it is syntax mainly because that solution works event without the Hercule tool. The Hercule syntax is also the closest to the one proposed for API Blueprint.

The most popular one at this moment is probably the syntax introduced in Aglio.

Concatenation solutions (Grunt task and Apiary manifest) feels simple but very limiting.

I am going to assume that this document is about temporarily supporting multiple API Blueprint files, right?

Hercule seems to support everything that Aglio's <!-- include(...) --> does, and it can be used as a library. I think the syntax looks good and if we go with that it seems like it would be relatively easy to add to Aglio. The older syntax can be transformed as a preprocessing step and the docs updated to push the new official syntax.

One question: does this mean that any URI will also be supported? e.g. :[Auth](http://example.com/auth.md)? Right now Hercule only supports local files as far as I can tell from the source.

I'm intending on introducing HTTP support in the future but haven't had time to do this. The other change I've been considering is supporting string and file inputs into the main transclude function. I imagine this would be useful for using Hercule as a library.

@danielgtaylor is it possible to get concatenated apib file from aglio which i can further use for api testing with a dredd tool?

never mind, i've found in source - https://github.com/danielgtaylor/aglio/blob/master/src/bin.coffee#L23