2

Starting with Apiary, I'm currently specifying the APIs for our project. I was able to define the definitions for the API and defining the parameters works great. enter image description here

Now I would like to add also the values passed in the HTTP Headers into my documentation (like pagination, version number of the API,...)

When browsing through the documentation I found that headers could be adden within the payload block or the request block, but I want them to be displayed in the documentation.

Is this possible and what's the best way to achieve this?

Mathias G.
  • 4,875
  • 3
  • 39
  • 60

2 Answers2

4

You can now use the Headers section.

Guido
  • 46,642
  • 28
  • 120
  • 174
  • 1
    Where do I write the documentation / description for a header entry? The documentation doesn't mention it. Thanks! – Daksh Mar 18 '18 at 17:29
2

Parameters are actually not required to be present in the URL template.

Thus, what you can do is to just have

+ Parameters
    + id (required, number, `1`) ... Numeric `id` of the Note to perform action with. Has example value.
    + X-My-Header (required, number, `5469`) ... My header does something

and this is going to be rendered in the table you mentioned as well.

You are going to have a warning from the parser, but it should work as expected.

Yami Odymel
  • 1,782
  • 3
  • 22
  • 48
Almad
  • 5,753
  • 7
  • 35
  • 53
  • Thanks for the reply. Yes I could do it like this, but I assume there is no way to make a distinction between parameters and header values that is foreseen in apiary? This way I'm abusing a bit the parameters table off course... – Mathias G. Jun 11 '14 at 14:23
  • 1
    Yes, there isn't a way to do such distinction yet. It is planned as [Parametric Headers Description](https://github.com/apiaryio/api-blueprint/issues/26), but it isn't implemented yet. – Almad Jun 11 '14 at 15:25