Descriptions for Request Attributes in Postman

Postman is introducing a new description column in the data editor making your requests easier to understand. You can now add comments and details for each of your query parameters, path variables, headers, and body (form-data and urlencoded) – all from right within the Postman app.

For example, specify if an element is required or optional, indicate the accepted data type, or use alternative terminology to provide additional clarification for developers who are working with your requests.

One step closer to comprehensive API documentation

For Postman Pro users publishing internal or public API documentation, these descriptions are displayed in the automatically generated documentation for that collection.

Note: Descriptions for path variables and URL params are currently NOT shown in the documentation.

You can hide and show the value and description column in the data editor by clicking on the ellipsis (…) in the top right corner of the editor, and unchecking the columns that you want to hide.

Note: Descriptions are metadata for a request and are NOT sent with your HTTP request. This reminder is displayed when you mouse over the title of the description column.

What do you think about this topic? Tell us in a comment below.

Comment

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.

20 thoughts on “Descriptions for Request Attributes in Postman

    When will URL Parameters be shown in Documentation?

      Hi Andrew, there is no ETA on this, but we’re working on this currently. Please stay tuned for latest updates!

        We are trying to document our API with Postman and because you don’t show path variables and URL params in the documentation, this process is a real pain.

          Hi Andre,
          Sorry to hear that – this is currently in the works, and will be out next month 🙂

    what is a necessary function is the team comments. The tester should have some way to leave comments on a team collection and notify the developer.

      Hi Zhuoran,
      Thanks for the suggestion! I agree – comments are a useful feature to have in a collaborative environment, and is a part of our long term roadmap. I’ve added this as a feature request anyway 🙂

    Any plans to add line-by-line descriptions for the body? The most complicated requests we see usually have complex objects in the body of the text, not just in the parameters.

    Hi Postman team,

    thanks for your hard work- I love what you have done so far. However, rendering path variables and URL params is a must. We are currently working around that problem with Markdown, but it is a really slow and painful process. Could you please provide an ETA?

      Hi Miro,
      We’re working on this currently, and hope to have it out by next month 🙂

    Is Path Variables supported for documentation? Because in Node we are having problem creating a documentation for path variable .

    For our documentation I was wondering if their is a way to tell that certain params are REQUIRED and what the DEFAULT value is if the user doesn’t add this parameter to the request

    I’ll start it from today! 🙂

    Right now it is in documentation for query params, however it still doesn’t show examples for body requests, any ETA on this?

    how if we want to set or define the object in the request body is required?

    I mean in APiary I can define it as
    + `object_name`:`Value` (string, required)

    how about postman ?

    Would it be possible to hide this column globally by default? I can see the benefit of having a Description field, but I don’t use it 95% of the time and it takes up a fair bit of screen real-estate, often truncating the parameter value forcing me to resize or hide the column every time