Annotate JSON request body for documentation

[ParasVarshney]

Is your feature request related to a problem? Please describe. I have a JSON body as a request payload and I would like to annotate the JSON body to provide more information as part of API documentation. However, JSON being a format that does not accept comments, makes any such out-of-json code be marked as invalid syntax and also gets sent as part of the request.

Describe the solution you'd like I would like to mention mandatory and optional fields in body with json content type like description.

Describe alternatives you've considered None

[shamasis]

@ParasVarshney - I have updated your issue title and formatted the body and rephrased the question to the way I understood and as per issue submission guidelines. Please verify whether this is what you wanted to convey.

If yes, then this is not something we have planned at all and would ideally like to implement the same in an alternate way, perhaps by extending the capabilities of our editor interface.

[a85]

Annotations will be part of the product but we don't plan to support that using inline schemas as that requires changing every data model that annotations could be part of.

[loris]

This is something really missing in Postman to properly document an API. APIs accepting JSON body are very common and there are currently no way to document them right now (at least a description field, but being able to set a default value, and a required boolean would be even better). What's weird is that the feature is already available if sending x-www-form-urlencoded or form-data bodies (but few modern APIs use them). My feeling is that, documentation apart, JSON body should have a first-class support in Postman, instead of using the raw tab

[arlemi]

Hey there!

With Postman 7.30 we've added a new feature that allows to comment on request elements such as query parameters, tests, body etc. You can use this feature to comment on the different values and say which ones are mandatory or optional.

Here's a quick GIF showing it in action:

And if you'd like to know more about it, I'd recommend the docs in our Learning Center: https://learning.postman.com/docs/collaborating-in-postman/commenting-on-collections/#commenting-on-a-request

[iwex]

@arlemi hi! why did you close this one? We need documenting, not commenting :)

[arlemi]

For documentation, you can use the request-level documentation and add as many details as you'd like, e.g.:

More info here: https://learning.postman.com/docs/publishing-your-api/authoring-your-documentation/#writing-descriptions-in-the-postman-editor

Alternatively, if adding JSON comments is the only option for you, a community member put together an example of parsing out comments before sending requests here: https://community.postman.com/t/postman-tip-and-tricks-add-comments-to-json-request-body-in-postman/43015

[alairock]

@arlemi

Creating a table per endpoint in a "text editor" is cumbersome, and does use features openapi spec 3 can provide, ie paths, refs, jsonschema, etc.

Competitors also use OAS3 to generate request bodies from jsonschemas, and jsonschemas from request bodies. This is what people are wanting and why people are leaving to stoplight when they hit this wall. Myself included at the last 3 companies I have worked at.

Per issues #3117, #3668, #3558, and I am sure others, and all the +1's, 👍 's and comments therein.

[toksdotdev]

It boggles my mind why this hasn't been prioritized. Automatically documenting body fields is a strong requirement for any API doc. OAS3 supports this, so I'm a bit puzzled why Postman doesn't want to support it.

As much as we like Postman, it's a strong blocker for us that we'll have to consider alternatives. I hope this can be looked into.

[skreutzberger]

What other tools are supporting it? I really need that feature, too. it is neither existing in Insomnia nor in Postman.

[iwex]

@skreutzberger check https://apidog.com/

[shashankawasthi88]

Hi,

I’m Shashank, a Product Manager at Postman. We’re exploring ideas for annotating request/response bodies, parameters, and more. This will allow you to provide additional details such as description, possible values, formats etc. for your JSON bodies and parameters.

Here is a recording of what the feature might look like. You can read more about the feature here.

This is in its early stages, and we’re seeking early adopters to try it out and provide feedback. If you’re interested, please reach out to me at [email protected] or schedule a call using this link.

Thank you!

[duykhanh412]

Hi,

I’m Shashank, a Product Manager at Postman. We’re exploring ideas for annotating request/response bodies, parameters, and more. This will allow you to provide additional details such as description, possible values, formats etc. for your JSON bodies and parameters.

Here is a recording of what the feature might look like. You can read more about the feature here.

This is in its early stages, and we’re seeking early adopters to try it out and provide feedback. If you’re interested, please reach out to me at [email protected] or schedule a call using this link.

Thank you!

Hi Shashank,

Thanks a lot for looking into this idea, it is a much much needed feature. I do have a few questions about the feature though, hope to get an answer from you:

1. Would we be able to use type definition with the Postman Collection SDK?
2. Would the openapi-to-postman module be able to convert a request/response schema in an OAS3 spec into the type definition in Postman?

We have a process to build our Postman collection based off the OAS3 specs so we hope that the type definition functionality will be made available with the Postman Collection SDK and the openapi-to-postman module.

Thanks.

[shashankawasthi88]

Hi @duykhanh412 ,

type definition support for Postman SDK and openapi-to-postman should be coming soon, it is not present in the product as we speak. Based on the feedback though, we may prioritize these items. Is it possible to setup a short call, if we can understand your usecase better, it will help us design that solution better. You can pick a time using this link or just drop me a message at [email protected] and ill setup some time.

[Trubador]

It would be nice if you could remove the inline comments from the json body before sending the request and without needing to write javascript in the pre request editor. Especially when testing apis and figuring out how they work before being documented fully it would be nice to set inline comments or similar on both request and response body to make it easy to figure out the apis data model. Commenting seems like not the best option for this as its purpose seems to be collaboration.

[shashankawasthi88]

@Trubador we are completely revamping this experience by giving you the ability to define types in collection that will let you provide descriptions for the JSON body as a separate object.

Here is a short demo for the same - https://www.loom.com/share/9662d9fdd2cb45a388f7d56b22b874ef?sid=ce717b1d-01b5-4ebd-8e25-581ca9a36748

Please drop a mail to me on [email protected] to get an early access. We can also schedule a short call using this to discuss this further.

[shashankawasthi88]

Hi All,

Happy to announce that we have launched feature that allows you to define Types in Collections, giving you the ability to annotate JSON bodies. Feel free to reach out to us if you have any feedback.

Cheers!