CODEWITHSUNDEEP
restapiblueprint
OrwellHindenberg
OrwellHindenberg

Reputation: 5078

Documenting Request Payload in apiblueprint

I've got a lot of API endpoints to document and the payloads of the POST and PUT requests can be complicated. I am documenting them with apiblueprint. I really like the way apiblueprint allows me to document URI parameters. It looks good and lets you provide the reader with all of the information they need such as (required, String or Integer, list choices/values and provide an example).

When we look at the Request section, however I'm not seeing how to provide the same level of pristine documentation. The request sections that I've seen just provide an example request.

Say we are dealing with a simple payload that just takes an integer named id that is required. Currently my request section would look like this,

Headers

Content-Type: application/json

Body

{"id":"123"}

Is the request body supposed to be this sparse? What is the best way to convey to my users all the constraints/requirements for my REST payloads?

Upvotes: 0

Views: 462

Answers (1)

Bishoy
Bishoy

Reputation: 4025

If I understand you correctly, you are looking for a way to documen your request paramters (headers, body, etc.)

If that's the case, then use the Schema section, and write a well documented JSON-Schema

for example you current simple request will look like this:

Request

    + Headers

        Content-Type: application/json

    + Schema

        {
            "type":"object",
            "properties":{
                "id": {
                    "type" : "string", 
                    "required": true
                }
            }
        }

    + Body

    {"id":"123"}

Upvotes: 1

Related Questions