CODEWITHSUNDEEP
restmarkdownapiblueprintaglio
GreenDroid
GreenDroid

Reputation: 347

Aglio does not allow parameters in the body to be defined as parameters

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?

Upvotes: 1

Views: 1336

Answers (1)

Daniel
Daniel

Reputation: 8772

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.

Upvotes: 2

Related Questions