Aglio, an API Blueprint renderer, does not allow parameters in the body of a request to be included in the parameters section of the the Endpoint specification. It throws parse warning as follows:
parameter '<some_parameter>' not specified in '<some_description>' its '<some_URI_template>' URI template (warning code 8)
A sample Markdown which would replicate this warning is:
## Journey creation [/v1/journeys/{origin}]
### Create journey [POST]
Create a new journey
+ Parameters
+ origin (required) ... origin location of journey
+ destination (required) ... destination location of journey
+ Request
+ Headers
Accept: application/json
Authorization: Basic <BASIC_AUTH_TOKEN>
+ Body
{
"destination" : "some_other_place"
}
+ Response 200 (application/json)
+ Body
{
"origin" : "some_place",
"destination" : "some_other_place",
"journey_state" : "Not_Started",
"timestamp" : "<dateuuid>",
}
The rendered does not like 'destination' to be a parameter, since it is not in the URI template.
My question is, is this a drawback of the tool, or is it an API Blueprint specificaton? Also, maybe, is this definition of a REST endpoint not per standards?
The correct way to specify message body attributes is using the new MSON attribute syntax, which is used to render JSON and JSON Schema as of Aglio 2.0.
### Create journey [POST]
Create a new journey
+ Parameters
+ origin (required) - origin location of journey
+ Attributes
+ destination: some_other_place (required) - destination location of journey
+ Request
+ Headers
Accept: application/json
Authorization: Basic
In the near future Aglio will render extra information for the attributes.