Document your APIs on Postman Cloud

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 🙂

8 thoughts on “Document your APIs on Postman Cloud”

  1. 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 ?

  2. 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?

  3. 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.

Leave a Reply

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