apiblueprint - 起草 API 蓝图文档时，如何对响应进行注释？

Question

我想注释一些错误响应，像这样:

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

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

但解析器(snowcrash)似乎将注释解释为响应主体。

如何注释这些响应并让 snowcrash 理解它们是注释？

Answer 1

我想通了:我需要在响应中添加一个空的 Body 部分，如下所示:

* 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

然后根据需要解析:

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: