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`.

但解析器（雪崩）似乎将注释解释为响应体。

我怎样才能注释这些响应并让雪崩明白它们是注释？

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: