Introducing support for JSON comments in your request body
To make it even easier for you to test and document your APIs effectively, we are thrilled to announce that Postman now enables you to add JSON comments in the HTTP request body.
JSON comments are annotations or notes that you can include within your JSON request body to provide additional context or explanations regarding the structure or purpose of the data being sent. Postman intelligently skips these comments while sending the request—and you can get really creative with how you leverage this feature to better document your API and workflows.
Improved documentation
JSON comments make your request body more verbose and understandable. You can use comments to provide explanations, examples, or guidelines for the expected values or formats of the request body. This can greatly help your team members or external consumers of your API to understand the purpose and structure of the request body, making it easier for them to integrate with your API.
Detailed testing experience
JSON comments can also be utilized to add comments and notes to your test cases in Postman. For instance, you can add comments to explain the expected results, highlight edge cases, or provide additional context for the test scenarios. This can be immensely helpful for your team members to understand the intent of the test cases and ensure that the API is functioning as expected.
We hope that support for JSON comments in Postman will further enhance your testing and documenting experience. Try it out for yourself and let us know what you think. If you have any questions, suggestions, or feedback, please feel free to reach out to us by leaving a comment below or via our GitHub repository.
Yesssssssssssssss
I have wanted this for so long – I maintain Postman collections for people who are very light on API experience/understanding, so inline comments are hugely helpful. Thank you!
This a great feature but with one issue. If u run request with JSON comments in your request body though Postman CLI these comments will not be erased from actual raw data and cause unexpected behaviour.
See example from Postman CLI in terminal: https://monosnap.com/file/jZde42SgU9mSBiMcZO9nJokTBlHtep
That’s a good point – in that case, it’s dependent not only on Postman supporting comments, but the end destination as well.
This is a valuable feature, but it poses some challenges in the context of the Postman CLI. For instance, when using the Collection Runner via the Postman CLI on a request that contains JSON comments in its request body, those comments are preserved in the raw data and can lead to unexpected test results.
Ex: https://monosnap.com/file/jZde42SgU9mSBiMcZO9nJokTBlHtep
To address this issue, a potential solution is to remove comments from the raw data when making requests through the Postman CLI.
Thank you.
Yes, I use it to leave comments on saved answers, reasons, final results, starting conditions that gave this result.
Are there shortcuts enabled to toggle comments inside the body editor? That’d be lovely