When drafting an API Blueprint document, how can I annotate a response?

Question

I’d like to annotate some error responses, like so:

* Response 412
If the Etag supplied in `If-Match` didn’t match.

* Response 428
If the request didn’t include the header `If-Match`.

but the parser (snowcrash) seems to be interpreting the annotations as response bodies.

How can I annotate these responses and have snowcrash understand that they’re annotations?

Answer 1

I figured it out: I need to add an empty Body section to the response, like so:

* Response 204

    The request succeeded; there’s no need to transfer a representation of the new state of the resource, as the resource no longer exists.

    * Body

* Response 412

    If the Etag supplied in `If-Match` didn’t match.

    * Body

This is then parsed as desired:

responses:
- name: 204
  description: "The request succeeded; there’s no need to transfer a representation of the new state of the resource, as the resource no longer exists.\n"
  headers:
  body:
  schema:
- name: 412
  description: "If the Etag supplied in `If-Match` didn’t match.\n"
  headers:
  body:
  schema:
- name: 428
  description: "If the request didn’t include the header `If-Match`.\n"
  headers:
  body:
  schema: