How do I add documentation / description to a Header parameter?

Question

For the Headers section, I need to describe what each header parameter / field / entry is. How would I go about doing that?

Currently, my Headers section looks like this:

+ Headers

        Access-Token: access_token # Server-generated Access Token to authenticate API calls from a user
        User-ID: user_id_from_google # Google-generated ID of each user
        Install-ID: randomly_generated_id # An ID to uniquely identify a device installation for a user

I am using # to imply that anything after that is a comment for that parameter.

Answer 1

It is not yet possible in the current version of API Blueprint to annotate headers inline.

You could move the description of the headers into the resource or action description. Using a table, you could provide the headers and descriptions. For example:

## GET /

### Headers

|Header|Description|
|------|-----------|
| Authorization| The authorization token |

+ Request
    + Headers

            Authorization: Bearer foo

+ Response 204

Which would be rendered in Apiary as follows:

In the future, we want to add MSON to headers in API Blueprint. Which will allow you to describe the headers inline (https://github.com/apiaryio/api-blueprint-rfcs/pull/3).