How to show an optional header in markdown for apiary?

Question

How to indicate that one particular header of a request is optional with the markdown of apiary?

My code:

• Request
  The apiKey can be passed in the header (note the camelcase for "apiKey")
  The Content-Encoding: gzip is optional, only if you gzip the entity

  • Headers

    apiKey: `42452-eofefo-4534535` (optional)
    Content-Type: application/json
    Content-Encoding: gzip (optional)
    

Is the above ok?

Answer 1

As of January 2016, it's not possible.

On the other hand—if you go to the API Blueprint Roadmap, there's MSON Parameters and Headers feature which is currently in the RFC stage; this will enable you to describe HTTP Headers in the MSON syntax and mark each HTTP Header as required/optional (see below).

+ Response 200 (application/json)
    + Headers
        + Date (Date, optional) - Date at which the message was originated

Hoping MSON Headers will land soon.