Документирование параметров запроса с помощью API Blueprint

Question

Я пытаюсь задокументировать параметр запроса в API Blueprint, но я не совсем уверен, правильно ли я это сделал. Ресурс выглядит так:

DELETE http://baasar.apiary-mock.com/user/{appId}/{userId}

Этот запрос будет деактивировать пользователя, в то время как следующий объект удалит объект пользователя:

DELETE http://baasar.apiary-mock.com/user/{appId}/{userId}?force=true

Это уценка Blueprint для этого:

## User [/user/{appId}/{userId}]
Handle user objects

+ Parameters
    + appId (required, number, `1`) ... Application ID (`appId`)
    + userId (required, number, `1`) ... Numeric `userId` of the User object to manage

### Remove an User [DELETE]
+ Parameters
    + force (optional, boolean, `false`) ... Set to `true` to remove instead of deactivate

+ Response 204

Однако при рендеринге с использованием пасеки я вижу только force в списке параметров, но теперь это показано в примере URL. Это только я неправильно понимаю GUI или параметры запроса должны быть задокументированы по-другому?

Answer 1

Ваш план в порядке, проблема в том, что текущая документация Apiary неправильно обрабатывает параметры URI.

Не могли бы вы попробовать новую документацию? Он должен правильно обрабатывать параметры URI.

редактировать

Правильный шаблон URI должен быть:

http://baasar.apiary-mock.com/user/{appId}/{userId}{?force}

Answer 2

Моя просьба о скручивании:

curl -k -u username:password https://api.techie8.io/api/1.0/bits?bit_type=1

План пасеки:

## Bits Collection [/bits?bit_type={bit_type}]

### List Latest bits [GET]

List all bits recently inserted into database.

+ Parameters
    + bit_type (number, optional, `1`) ... Type of bit to retrieve: 1: Bits, 2: Newsletter