Geek Answers Handbook

Response description and POST parameters in the Blueprint API

I tried the Blueprint API and found some things that I don’t quite understand.

1. How can I document POST body parameters?

There is + Parameters , but it just documents the request parameters. If I want to describe the POST API now, I cannot document the POST parameters (application / x-www-form-urlencoded). The same goes for JSON (see No. 3).

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

I tried

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

But it just adds the text as the answer of the body.

3. Describe the various fields of my answer

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

Thanks!

+8
apiblueprint
source share
1 answer

Let's see # 1 and # 3 together, as they are closely related:

Description of payload fields

There is currently no special syntax for discussing the actual payload fields (model, response, or request).

Now you decide how you describe it using any Markdown syntax you like.

It is planned to provide Markdown syntax for discussing these fields / parameters as follows:

JSON:

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

and its description in the project:

 - 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 information can be found here .

Answer Description

You can already add any legend formatted discussion to the payload

 # Resource [/r] ## List [GET] + Response 200 This response will list the R + Body { ... }

More info here: https://stackoverflow.com/a/316677/

Note. For the description to display correctly in Apiary, you may need to use the "New Documentation Provided by Apiary"

+9
source share

More articles:


All Articles