Carson Hunter - Creating Interactive Docs with Postman

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

Docu-mentor

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.