养蜂场:是否可以记录什么是JSON响应字段? [英] Apiary: Is it possible to document what JSON response fields are?

问题描述

我想证明实际JSON字段本身代表什么.

I would like to document what the actual JSON fields themselves represent.

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

I have documented the GET statement, and parameters but this does not make a complete documentation to give to users.

因此，在下面的示例中，我将如何添加有关"OtherFields"的注释.支持这个吗?还是我需要在其他地方制作配套文档.

So, in the example below how would I add a comment about "OtherFields". Is this supported? Or do I need to make a companion document somewhere else.

## 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: ""
               }]
               }}

推荐答案

更新:我们刚刚使用 MSON语法.

Update: We have just rolled out a beta of attributes description using the MSON syntax.

原始有效载荷可以描述为

The original payload could be then described as

### 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蓝图规范– 属性了解更多详情

Note the explicit JSON in body is redundant and you can skip it completely. See API Blueprint specification – Attributes for additional details

这篇关于养蜂场:是否可以记录什么是JSON响应字段?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！