Skip to main content

Carson Hunter - Creating Interactive Docs with Postman

API the Docs Virtual Event Series 2021 Recap

This talk was presented at API The Docs Virtual 2021 event series on 13 July. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Carson's presentation (video recording)

Carson's slides


How to make your Postman API documentation more interactive and informative? How can you visualize complex objects in Postman and improve your documentation process? The Postman Hackathon winner, Carson Hunter tells a story about how she and her colleague won the challenge and what documentation tools they developed on the way.


Previous workflows

  • Automatically generate OpenAPI Specifications from code
  • Automatically “translate” them over to Postman collections
  • Use Postman to add more context, and create markdown model tables by hand



The idea: Let’s build a public workspace where developers could go with their collection they’re already started working on, and they could amp up their documentation in different ways.

The Docu-mentor project consists of two parts:

  • Model Creation Collection: creates and injects OpenAPI-esque markdown tables
  • Documentation Assistant Collection: helps to track documentation coverage

Model Creation Collection

Adds OpenAPI-esque models to Postman documentation by:

  • Discovering the response and request models from the API’s JSON representation
  • Creating markdown tables describing the response and request models
  • Including linking to nested models and to other requests that use those models

Users now have an automatically generated thorough reference for every request and response of the API:

  • All the object models are getting listed in a separate folder on the left navigation in Postman

  • The representation of the model is displayed on the right with the:

    • list of properties
    • data types
    • links to the nested objects

The only manual step you need to do is to provide the description after the main content and structure of the documentation are automatically generated.

Documentation Assistant Collection

Like a code coverage report, but for documentation.

  • Grabs a Postman collection
  • Gets a report back in Postman visualizer format, listing out:
    • the documentation-related tasks still left to do
    • the percentage of the completeness of the documentation based on the given standards
    • links to suggested resources, like useful blog posts and articles

The algorithm is built inside Postman request scripts, and the reports can be displayed on Slack.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.

Sign up


Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.