I'm trying to document a query parameter in API Blueprint, but I'm not entirely sure if I have done it correctly. The resource looks like this:
DELETE http://baasar.apiary-mock.com/user/{appId}/{userId}
That request would deactivate the user while the following would delete the user object:
DELETE http://baasar.apiary-mock.com/user/{appId}/{userId}?force=true
This is the Blueprint markdown I have for this:
## 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
However, when rendering this with Apiary I only see force
in the list of parameters, but it is now shown in the example URL. Is that just me misunderstanding the GUI or should query parameters be documented in another way?
Your blueprint is perfectly fine, the problem is that the current Apiary documentation does not handle URI parameters correctly.
Could you please try the new documentation out? It should handle URI parameters properly.
Edit
The correct URI Template should be:
http://baasar.apiary-mock.com/user/{appId}/{userId}{?force}
My curl request:
curl -k -u username:password https://api.techie8.io/api/1.0/bits?bit_type=1
Apiary blueprint:
## 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
来源:https://stackoverflow.com/questions/22845666/documenting-query-parameters-with-api-blueprint