Document your APIs on Postman Cloud

Avatar

When working with APIs on a team, a lot of time and energy is consumed in making sure everything is documented and up to date. We know we faced these challenges here on the Postman team. So, of course, it was a no-brainer to build in auto-updating documentation for your APIs.

Some of you might already be aware of Postman’s Documentation feature. Check out a sample at Postman Echo.

 

  • With Postman Cloud, all collections are automatically documented and instantly accessible by all members of your team!
    We’ve included a ‘View Docs’ button in the team library (for all shared collections in the team), as well as in Postman’s sidebar (for your own collections, or any that you have subscribed to).
  • Clicking this button for any collection should take you to a page like this:
    sample-docs
  • All data on this page is updated instantly with any edits made to the collection. The mini control-panel on the top-right is worth a mention too.
  • The environment selector will instantly replace any references to environment variables ( {{id}}, for example) with values in the selected environment. Here’s what the cURL snippet of the first request looks like by default:
    curl-default
  • And here’s what it looks like when I select my Sgt. Pepper environment (notice that the {{id}} has changed to the value from the environment):
    env-curl
  • Of course, cURL might not be your cup of tea. You might prefer to use Postman. Or Ruby:
    env-ruby

The next big update to the documenter involves the ability to publish documentation to the outside world. You’ll be able to generate a publicly-accessible URL, with the environment info baked in, for anyone to access. Expect another blog post soon πŸ™‚

Note: Postman Cloud is now called Postman Pro.

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.

8 thoughts on “Document your APIs on Postman Cloud

    Avatar

    Wow. Postman is making some progress. I like that new feature!

    Avatar

    This is great but these changes have now made my existing documentation look terrible because I used markup indicators such as ####.

    Where can we go to view documentation that will show up how to best use this new feature ?

    Avatar

    This is very nice indeed. And can’t wait for your next “big update”. Do you have an ETA on that?

      Avatar

      This is out now! Postman Cloud teams can publish public documentation URLs.

    Avatar

    how to call java method inside Test tab in postman collections?

    Avatar

    I like this but my company will not allow me to send customers to your endpoint. How about an API that let’s me pull this… html or markdown?

    Avatar

    How to specify the validation points like username is required, mobile is required and digit range should be in between the 10 and 12 in the documentation.