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!

Blaze

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://mcmap.net/q/1316839/-specify-description-for-every-response-we-have-in-apiary-io

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

Terrellterrena

Note: If your response have empty body but you still need the description there you need to append + Body without any content. This is the unfortunate tradeoff for the abbreviated body syntax – Terrellterrena

Thank you very much! Is it possible that for #2 the comment is only shown, if there is a mime type? Your example will not show a comment (at least when I tried it), but only if I add the mime type. – Blaze

Nope that should not be needed. I have just tested it and it works good - see docs.desctest.apiary.io, please send email to [email protected] if it does not work for you (note make sure you have "New Documentation" turned on in settings) – Terrellterrena

I spent like 4-5 intense hours browsing the full Blueprint lang spec and the apiary website trying to answer exactly the same questions as the OP - how to specify a request parameter. It is 2019 - 5 years since this answer was posted and now it turns out that there is still no way of specifying a request parameter!!! Yes, an API documentation tool that has no concept of request parameters. – Unseal