Extensions

Extensions

I love API Blueprint but it is missing some stuff I found to be awesome

Including Files

It is possible to include other files in your blueprint by using a special include directive with a path to the included file relative to the current file's directory. Included files can be written in API Blueprint, Markdown or HTML (or JSON for response examples). Included files can include other files, so be careful of circular references.

<!-- include(filename.apib) -->

For tools that do not support this include directive it will just render out as an HTML comment. API Blueprint may support its own mechanism of including files in the future, and this syntax was chosen to not interfere with the external documents proposal while allowing PHPDraft users to include documents today.

Thanks to aglio for the idea.

HOSTS

Apiary allows you to set a HOST keyword in your metadata, this allows them to generate requests for you. That's pretty cool but you know what's even cooler? Selecting anything in your DTAP stack from a dropdown.... Yup, we allow that. Just use comma separated hosts in your file. They'll be added to the HOST parameter you probably already had defined for optimal compatibility.

HOST:https://google.com
ALT_HOST:https://dev.google.com,https://acc.google.com

OpenAPI API Key configuration

If you want to render OpenAPI with a security configuration, you can define how the API key looks in a header using the following extension fields:

API_KEY_HEADER: X-API-Key # The API Key header name
API_KEY_LOCK_ALL: false   # Should the API Key lock all APIs?

Extra info

If you want to show the user more info, add more metadata like the stuff above. Anything you add there will be shown in an "Extra info" dialog you'll find in the bottom-left corner.

disclaimer: You can't use 'HOST', 'TITLE', 'ALT_HOST', 'FORMAT' or 'DESC' those are mine and mine alone.