Feature Request: Add ability to document a raw body request

[CosmicBara]

I noticed that the latest version of the Postman app for Windows includes support for documenting the request parameters, headers, and the body. However, it seems only the form-data and x-www-form-urlencoded types are supported for documentation. Is it in the pipeline to support documenting of the raw request body? I know JSON does not support comments by default, but if you guys provided some way to provide documentation so we can explain what each parameter in the JSON object represents, that would be super useful.

[a85]

@GunslingerBara You can use the request body markdown to do this. We support tables too so you can document JSON structures. I'd love to hear suggestions on how to document JSON objects. :)

[CosmicBara]

@a85 What exactly do you mean by "request body markdown"? Is there a page in the Postman documentation that details this, or an example you can share?

[sdnts]

Hi @GunslingerBara You should be able to document Raw bodies in the Request's description. We'll look into supporting docs for raw body as well.

[a85]

@GunslingerBara Have a look at our docs: https:https://www.getpostman.com/docs/postman/api_documentation/how_to_document_using_markdown

[govindrai]

@madebysid Shouldn't this be open? I know we can use the description section and markdown for documenting raw body, but it's cumbersome and I know it would make the documenter that much powerful.

[govindrai]

@a85 one idea is to simply mirror what you have for form-data and x-www-form-urlencoded in addition to being able to type out raw bodies. It would be even better if you could determine from the JSON or XML structures nested fields and autopopulate the key column. That would be ideal.

[a85]

@govindrai We have a new data editor in works that will allow for this but we might have some work to do on the data structure. I'll reopen this.

[aichholzer]

While you can add descriptions to form-data parameters, there is no way to do the same for JSON request bodies. Also, the markdown editor seems like a hack around this. Parameter or body descriptions should be consistent and handled by Postman in a similar way.

Any further progress with this?

[Sutty100]

+1 on an update!

This is a blocker for us using postman pro as we can not document our API's request/response JSON models to the same level that we can with swagger

[lukaswelte]

+1 I would love to have the ability to document JSON APIs using Postman. In order to do that I need to make explicit how the schema for my request and my response looks like (what fields are required, which are optional and what are potential values like e.g. the values of the enum).

Would be awesome to be able to define a schema (name & describe required fields) for request JSON data as well as the response. This schema could then even be integrated with the tests to check this same schema there.

Would be great to resolve that blocker which keeps us away from integrating Postman into the process in our company.

[reid3290]

+1 Not able to comment on raw json request is really not a good idea.

[Sridatta19]

+1 Hope this feature arrives soon

[eranhazout]

+6 (we are a team ;) Required fields should be very useful

[pmilanez]

+2 👍 this will be a game changer

[steeveroucaute]

+1 not being able to comment and properly document a JSON payload is a blocker for me. Swagger has data models which is way more useful to document complex objects.

[markus-ethur]

+1 Agree totaly, we should have some kind of comments

[kausality]

+1

This is one of the reasons I had to rescind our published API docs from Postman back to Swagger.

[eiyiaioyou]

+1

[CosmicBara]

It will soon be a year since I made this suggestion, and I haven't seen any feedback on potentially implementing this feature. Throughout this past year, I've received emails consistently from people +1 or showing their support. Can Postman devs please provide an official response as to whether or not they will implement this request?

[djly]

+1, as we use json body for all our requests, I might have to start looking for another solution. Was really hoping postman would support this.

[kheengz]

Wish this Feature Request: Add ability to define required/optional fields/headers and field types will be added soon

[armyofda12mnkeys]

I agree, would be great to allow comments (even if you had to 'opt into' this feature [via a checkbox in the Request Area] on the specific Request that would be fine).

Sometimes I want comments to describe that param, or to suggest alternate values to copy/paste to test, or maybe quickly comment out a param or a group of params when testing our web services.

@a85 saw you self-assigned to this yourself. Does that mean its officially being looked at to implement ? Do you think it will be coded so you can use regular single-line comment // and block-style / / coding comments within the JSON Body?

[bt-dd]

+1 As others have brought up, this would be an extremely useful feature, hopefully it will eventually be added to Postman!

[fireice009]

+1. Especially now support for publishing documents. We use it for API document.

[bj97301]

help yo

[Sirsksk]

Hi! I'm trying to document a raw-XML body... I don't know if there is a solution for that.. yet just asking :)

[mehdichati]

+1 , for this feature , for any assumed professional API (required/ optional) input field is mandatory.

thanks for your help.

[AxonDivisionDev]

This should be a huge priority, ability to visual showcase the validity of a field quickly is incredibly important. The entire logic of a program can be shifted based on whether an attribute exists or not.

[eriadam]

@a85 @vkaegis Any update from you guys would be much appreciated.

[mikecousins]

Any idea if this will be improved shortly? Our company is about to make our purchasing decision and this will weigh heavily on it. Thanks.

[vkaegis]

No ETA on this yet. This is a huge priority for us as well, but we have some prerequisites to be taken care of.

[abes-dabir]

+1

[ray-kay]

+1 @a85 any update/timeline on this? I am new to global IT consultant company (16k employees) and I would like to establish Postman as dev. documentation tool #1 but not to being able to document individual fields in a JSON BODY request/response like to you can in swagger is big blocker.

thanks

[mcelhennyi]

+1 this is needed big time!

[kevinohara80]

FWIW, this is preventing our team from moving to Postman Pro and we're looking at Swagger Hub instead. We'd much rather use Postman!!!

😔

[adrianovcar]

+1

[w3b5urf3r]

+1. I don't see why this is not happening yet!! first post on 6 Jun 2017 !

[Almesia]

+1

[Hrafnkellos]

+1

[jordanebelanger]

Make it happen already, it's not an hard feature to add and would make documenting using postman requests ACTUALLY possible :)

[rorykoehler]

+1 Not having this feature makes Postman practically unusable

[AxonDivisionDev]

Working with JSON:API and a dev team where we really need this feature. Our workaround is to leave raw attributes empty if nullable types, obviously not ideal nor is it explicit 👎

[valentim-guilherme]

+1 waiting for this feature for years!

[dchurchland]

+1 Documenting JSON body is the difference between my team using or not using Postman. Here am I hoping we get to use it...

[bheddens]

Would love to see the ability to document JSON body raw, otherwise, documentation looks clunky in the description.

[loris]

+1 this is currently blocking our enterprise from moving their api documentations to Postman

[aaronn]

+1– was choosing between Postman and Swagger and was kind of shocked this wasn't supported. We need the ability to document what kinds of fields are going to be required or optional, and stuffing them into form-data doesn't feel like a good way to do this.

[abhisekp]

The editor may use JSON5 to support comments in the json. :rocket:

EDIT: I tried to use code markdown in request description.

In Postman (while editing)

Code Highlighting

In Postman (in view mode)

No Code Highlight

In Postman Documention online

No Code Highlight

[lukaswelte]

That is nice :) But sadly not comparable to schema which contains information like type and if optional or not (and can be read by a machine instead of a human reading the comments)

[loris]

I also think that JSON comments is not the best solution. Would be better to have a real JSON editor like Postman have for simple key/value dictionnary (headers, parameters, etc) but with added support for nesting and complex values. Have a look at the plist editor from XCode :