apiblueprint - API蓝图中的响应描述和POST参数

Question

我正在尝试API蓝图，发现了一些我不太清楚的东西。

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中找到更多详细信息。

回应说明

您已经可以添加任何markdown 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