如何为 json 请求对象指定可选元素答案

【问题标题】：How to specify an optional element for a json request object如何为 json 请求对象指定可选元素
【发布时间】：2014-03-29 17:08:47
【问题描述】：

在 API 蓝图中，我希望为 POST 消息指定一个可选的 json 元素。示例；

    ### Add a new User [POST]
    To add a User send a JSON .....

    + Request (application/json)

    {
         "name": "A name",
         "age": 30
    }

如何向 API 的读者表明年龄在 API 调用中是可选的，但仍显示它是一个整数？

~科林

【问题讨论】：

标签： json apiblueprint

【解决方案1】：

我推荐像这样的文档字段表。

### Source Fields

| field      | required | type | example                                | description |
|------------|:-:|-------------|----------------------------------------|-------------|
| name       | * | string      | `average-lead-time-frontend`           | Unique name for machines, used as reference key and for url usage. |
| title      | * | string      | `Average Lead Time Frontend`           | Title for humans. |
| sourcetype | * | string      | `team-avgLeadTime`                     | Source type identificator. |
| groups     |   | list        | `["engagement-analytics", "builder"]`  | List of groups where entity is member. |
| options    |   | object      | `{ "team": 21926 }`                    | Addition options for sourcetype. |
| data       |   | list        | `[70.3, 31.8]`                         | Actual data held by Source. |

生成的字段表：http://i.stack.imgur.com/cxocx.png

【讨论】：

【解决方案2】：

目前没有专门支持这样做。但是，实现这一目标的方法很少。

我更喜欢使用您喜欢的降价格式在请求描述中讨论它，例如：

### Add a new User [POST]
To add a User send a JSON .....

+ Request (application/json)

    Data about user being created. Where age attribute is optional.

    + Body

            {
                 "name": "A name",
                 "age": 30
            }

或许：

To add a User send a JSON .....

+ Request (application/json)

    Data about user being created. With following attributes are:

    + `name` ... name of the user
    + `age` (optional) ... age of the user

    + Body

            {
                 "name": "A name",
                 "age": 30
            }

请参阅http://docs.gtdtodoapi.apiary.io 文件夹集合资源以获取更多示例。

您还可以始终指定描述正文负载的 JSON 模式。请注意，对讨论消息正文属性的专门支持正在制定中 (https://github.com/apiaryio/api-blueprint/issues/25)

【讨论】：

谢谢，我根据您的第一个示例添加了评论，但更喜欢您的第二个示例 - 我可能会稍作调整并添加标题并仅列出可选参数。