How do I add documentation / description to a Header parameter?
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.
Solution
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).
- API Blueprint - Avoid repeating authorization blocks
- How do I document a multipart request with apiary?
- Is it possible to center tables in a markdown file?
- Apiary: Is there a way to define options for parameters?
- How do I use another gem as a dependency and create a class that inherits from it
- How can I add images/diagrams to API Blueprint?
- apiblueprint response download file
- How can I create a nested table of contents in apiary?
- How to supply example value for string array parameter in api-blueprint
- What is distinctive purpose of API Blueprint vs Swagger?
- Render apiary documentation locally with the V4 interactive documentation
- Sails 1.0 cannot access autogenerated associated entity routes
- How can I use apiary with JSON-RPC
- How to create object field in api-blueprint?
- How to exclude a test from appearing in the documentation
- api blueprint mson object with different values
- ApI blueprint Date format
- Dredd Apiary contract driven test - Is there any way to access private apiary documentation blueprint format from local dredd config?
- Rendering attributes on aglio?
- Good rest code generation and documentation tool
- http authentication using apiary / api blueprint
- Apiary Blueprint attributes under headers and body are not recognized
- Is it possible to define a fixed array length in API Blueprint?
- Do IBM Bluemix and Azure provide equal support to API Blueprint and OpenAPI? To describe APIs
- How do I add documentation / description to a Header parameter?
- Api blueprint failing with dredd on a realtime api?
- Documenting query parameters with API Blueprint
- MSON to JSON-Schema "One of" issue
- Dredd failing to parse apiblueprint response body
- Ambari cluster + what is the right syntax in order to upload blueprint json file to ambari cluster