API蓝图中的响应描述和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,因为它们密切相关:

有效负载字段的描述

目前,没有专门的语法来讨论有效载荷的实际字段(模型,响应或请求).

现在,您可以使用任何您喜欢的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)

我目前正在研究这个问题.更多细节可以在这里找到.

回复说明

您可以将任何降价格式的讨论添加到有效负载

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

    This response will list the R

    + Body

            { ... }

更多信息:https://stackoverflow.com/a/19433269/634940

注意:为了使描述在Apiary中正确显示,您可能需要使用New Apiary Rendered文档