Response description and POST parameters in API Blueprint

Question

I am trying out API Blueprint and found some things, which are not quite clear to me.

1. How can I document POST body parameters?

There is + Parameters but it just documents query parameters. If I now want to describe a POST API I can't document POST parameters (application/x-www-form-urlencoded). The same goes for JSON (see #3).

2. Is there a way to add a description to a response?

I tried

+ Response 403
If the request request is made with HTTP instead of HTTPS.

But this just adds the text as the body response.

3. Describe the different fields of my response

If I return JSON I want to describe each field separately, its type and its purpose. Is there a way to do that?

Thanks!

Answer 1

Lets look #1 and #3 together as they are closely related:

Description of payload fields

Currently there is no dedicated syntax for discussing the actual fields of a payload (model, response or request).

For now it is up to you how do you describe it using any Markdown syntax you like.

The plan is to provide a Markdown syntax for discussing these fields / parameters like this:

JSON:

{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}

and its description in blueprint:

- id: 1 (integer) - The unique identifier for a product
- name: A green door (string) - Name of the product
- price: 12.50 (number)
- tags: home, green (optional, array of strings)

I am currently working on this. More details can be found here.

Response description

You can already add any markdown formatted discussion to a payloads

# Resource [/r]
## List [GET]
+   Response 200

    This response will list the R

    + Body

            { ... }

More info here: https://stackoverflow.com/a/19433269/634940

Note: In order for the description to appear correctly in Apiary you might need to use the New Apiary Rendered documentation