在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调用中的年龄是可选的,但仍然显示它是一个整数?
〜科林
答案 0 :(得分:4)
我推荐像这样的文档字段表。
### 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. |
答案 1 :(得分: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)