Apiary：是否可以记录 JSON 响应字段是什么？

Question

我想记录下实际的 JSON 字段本身所代表的内容。

我已经记录了 GET 语句和参数，但这并不能提供给用户的完整文档。

那么，在下面的示例中，我将如何添加关于“OtherFields”的评论。这支持吗？或者我是否需要在其他地方制作配套文件。

## View Applications [/cat{?sort}{&order}{&page}]
### List all Applications 
### Get List of Applications [GET]
+ Parameters
    + sort (optional, string) ... `sort` parameter is used to specify which criteria to use for sorting. One of the following strings may be used: 
    `"NAME", 
    "RATING", "QUALITY" ,
    "RISKLEVEL", `

    + order (optional, string) ... `order` parameter is used to specify which order to use if sorting is used. One of the following strings may be used: 
    `"ASC", 
    "DESC"`

    + page (optional, int ) ... `page` parameter is used to request subsequent catalog pages.


+ Response 200 (application/json)

                {
            "Catalog" : {
                "Page" : 0,
                "Count" : 6,
                "Applications" : [{
                        "UID" : "6882e96a-5da1-11e3-1111-3f24f45df3ad"
                        "OtherFields: ""
               }]
               }}

Answer 1

我认为还不支持。

我在我的项目中解决了这个问题，方法是在 GET 请求行的正上方放置一个带有描述的表格。在您的情况下，它可能看起来像：

### List all Applications 

| Field                            | Description               |
|----------------------------------|---------------------------|
| Catalog.Applications.OtherFields | Documentation goes here.. |

### Get List of Applications [GET]

为了帮助您以 Markdown 语法创建表格，您可以使用 Markdown Tables generator。

请注意，表格生成器允许您将表格定义保存到文件中，因此下次您需要编辑表格时，您可以从上次中断的地方开始。

Answer 2

更新：我们刚刚推出了使用 MSON syntax 的属性描述测试版。

原始有效载荷可以描述为

### Get List of Applications [GET]

+ Response 200 (application/json)

    + Attributes
        + Catalog (object)
            + Page: 0 (number) - Number of the page
            + Count: 6 (number) - Count of *Lorem Ipsum*
            + Applications (array) - Some array of something
                + (object)
                    + UID: `6882e96a-5da1-11e3-1111-3f24f45df3ad`
                    + OtherFields

    + Body 

            {
                "Catalog" : {
                    "Page" : 0,
                    "Count" : 6,
                    "Applications" : [{
                        "UID" : "6882e96a-5da1-11e3-1111-3f24f45df3ad"
                        "OtherFields": ""
                    }]
                }
            }

注意正文中的显式 JSON 是多余的，您可以完全跳过它。有关更多详细信息，请参阅 API 蓝图规范 - Attributes