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
}
How do I indicate to reader of API that age is optional in API call but still show that it's an integer?
~Colin
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
}
or perhaps:
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
}
See http://docs.gtdtodoapi.apiary.io Folder Collection resource for a futher example.
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)
I recommend table of document fields like this one.
### 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. |
Generated table of fields: http://i.stack.imgur.com/cxocx.png
来源:https://stackoverflow.com/questions/22734103/how-to-specify-an-optional-element-for-a-json-request-object