API Blueprint中的响应描述和POST参数

Question

我正在尝试API Blueprint并找到了一些我不太清楚的事情。

1。如何记录POST正文参数？

有+ Parameters但它只是记录查询参数。如果我现在要描述POST API，我无法记录POST参数（application / x-www-form-urlencoded）。 JSON也是如此（参见＃3）。

2。有没有办法在响应中添加描述？

我试过

+ Response 403
If the request request is made with HTTP instead of HTTPS.

但这只会将文字添加为身体反应。

3。描述我的回复的不同领域

如果我返回JSON，我想分别描述每个字段，它的类型和目的。有没有办法做到这一点？

谢谢！

Answer 1

让我们一起看＃1和＃3，因为它们密切相关：

有效负载字段描述

目前，没有专门的语法来讨论payload（模型，响应或请求）的实际字段。

现在由您决定如何使用您喜欢的任何Markdown语法来描述它。

计划是提供Markdown语法来讨论这些字段/参数，如下所示：

JSON：

{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}

及其在蓝图中的描述：

- id: 1 (integer) - The unique identifier for a product
- name: A green door (string) - Name of the product
- price: 12.50 (number)
- tags: home, green (optional, array of strings)

我目前正在研究这个问题。可以找到更多详细信息here。

响应说明

您可以添加任何降价formatted discussion to a payloads

# Resource [/r]
## List [GET]
+   Response 200

    This response will list the R

    + Body

            { ... }

此处有更多信息：https://stackoverflow.com/a/19433269/634940

注意：为了使描述在Apiary中正确显示，您可能需要使用New Apiary Rendered documentation