How to document POST parameters with Apiary?

Question

I've written a small web service that was designed to be "curl-able", so it relies on application/x-www-form-urlencoded parameters in POST requests, e.g.:

curl http://api.example.com/ -d param1=foo -d param2=bar

I would like to document this service using Apiary, but I've been unable to figure out a way to provide structured documentation for these parameters. I can provide an example request like this...

+ Request (application/x-www-form-urlencoded)

        param1=foo&param2=bar

...but this doesn't allow me to provide documentation on the individual parameters (and does not lend itself well to testing in the apiary console, since it is unable to provide input fields for the various parameters).

I've read through the api blueprint specification a few times and I've been unable to find a good solution. Is there any way to provide structured documentation for these parameters?

Answer 1

You can use Attributes for this type description.

FORMAT: 1A

HOST: http://api.example.com/

# Test attributes 1

## Create post [/]

### Create a Post [POST]

+ Attributes
    + param1: foo (string) - Foo param
    + param2: bar (string) - Bar param

+ Request (application/x-www-form-urlencoded)

+ Response 201