如何为JSON请求对象指定可选元素 [英] How to specify an optional element for a json request object

问题描述

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

In API blueprint I am looking to specify an optional json element for a POST message. Example for;

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

    + Request (application/json)

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

如何向API的读者表明年龄在API调用中是可选的，但仍然表明它是整数?

How do I indicate to reader of API that age is optional in API call but still show that it's an integer?

〜科林

推荐答案

当前尚无专门的支持.但是，有几种方法可以实现此目的.

Currently there is no dedicated support for doing this. However there are few ways how to achieve this.

我最好在请求说明中使用自己喜欢的降价格式来讨论它，例如:

My preferable is to discuss it in the request description using a markdown formatting of your liking e.g:

### 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 文件夹集合资源.

See http://docs.gtdtodoapi.apiary.io Folder Collection resource for a futher example.

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

You can also always specify a JSON schema describing the body payload. Note dedicated support for discussing message body attributes is in the making (https://github.com/apiaryio/api-blueprint/issues/25)

这篇关于如何为JSON请求对象指定可选元素的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！