Document API Raw Request Body (JSON)

As a Postman user, I’d like to be able to document the request body when using a raw request so that other users know what the request body properties are.

The description is too free form which increases the boiler plate for documentation. OAS allows me to do this and is a big reason to keep using OAS/Swagger.

Another person requesting help with this - JSON Post Body Documenting Parameters

2 Likes

Hey @joshua,

Making a raw request body look like the form data is not possible because, as you probably know, JSON can include nested objects, so the structure itself is more complex.

How does it work in OAS/Swagger? Can you share a screenshot?

There are two options that you could explore in Postman:

API Tool

This allows you to define a schema (with OpenAPI/Swagger). I admit, this is a rather formal way of specifying a description of the parameters, but I wanted to point it out anyway.

You can then link the schema and the collection in Postman.

Using JavaScript

You can use JavaScript to define your request body and use comments to say what each property does:

You can find on YouTube a short tutorial created by me explaining how this works: https://www.youtube.com/watch?v=hSX7Dcjy000

I hope one of these two options provide a temporary solution.

2 Likes