Aglio не позволяет параметрам в теле быть определенными как параметры

Question

Aglio, средство визуализации API Blueprint, не позволяет включать параметры в теле запроса в раздел параметров спецификации Endpoint. Выдает предупреждение о разборе следующим образом:

parameter '<some_parameter>' not specified in '<some_description>' its '<some_URI_template>' URI template (warning code 8)

Пример уценки, которая будет повторять это предупреждение:

## 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>",
            }

Рендеринг не любит, когда 'destination' является параметром, поскольку его нет в шаблоне URI.

У меня вопрос, является ли это недостатком инструмента или это спецификация API Blueprint? Кроме того, может быть, это определение конечной точки REST не соответствует стандартам?

Answer 1

Правильный способ указать атрибуты тела сообщения - использовать новый синтаксис атрибута MSON, который используется для визуализации схемы JSON и JSON начиная с 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 

В ближайшее время Aglio предоставит дополнительную информацию для атрибутов.