Download to read offline
Uploaded byPronovix
Creating Interactive Docs with Postman
The document details a Postman hackathon project led by Carson Hunter, focusing on creating tools for better API documentation. It introduces the Model Creation Collection, which generates OpenAPI-like markdown tables for requests and responses, and the Documentation Assistant, which evaluates the completeness of existing documentation. Resources are provided to help users implement these tools in their own Postman projects.
Creating Interactive Docs with Postman
- 1. @carrrson Creating Interactive Docs withPostman How we won the Postman Hackathon and the documentation tools we created along the way Carson Hunter Metadata Technology North America/Postman
- 2.
- 3. Generating from our Swagger/OpenAPI files Creatingby hand Previous workflows Creating markdown model tables by hand @carrrson
- 4. How can weget this Swagger/OpenAPI functionality in Postman and improve our docs process? Hackathon Brainstorming @carrrson
- 5. d ocu-mento r d ocu-mento r Create and injectOpenAPI- esque markdown tables with the Model Creation Collection Keep up with documentation coverage with the Documentation Assistant Collection @carrrson
- 6. Part 1: TheModel Creation Collection Your users now have a thorough reference for every request and response in your API. We'll discover your request and response models, then create and insert markdown tables describing them, including linking to nested models and the other requests that use them. Original Postman Documentation Collection Run them through the Model Creation collection Adding OpenAPI-esque models to Postman documentation @carrrson
- 8. Part 2: DocumentationAssistant Grab a collection you've already started documenting Run it through the Documentation Assistant's algorithm (built inside Postman request scripts) Get a report back (in Postman visualizer format) listing out what's still left to do, the percentage complete, and suggested resources to help you along the way Like a code coverage report, but for documentation @carrrson
- 9.
- 10. How you can usethese tools Use the MTNA Java models to create your own Postman projects Fork the collection(s) from the Docu-Mentor Postman workspace and run then on your own collections Use the MTNA Newman Example Generator to add examples to your current Postman collections @carrrson 1 2 3
- 11. Resources MTNA's Java PostmanModels, Newman Example Generator, and Docu-Mentor Java API: https://github.com/mtna/postman-utils Docu-Mentor DevPost submission with video: https://devpost.com/software/docu-mentor @carrrson Docu-Mentor Postman workspace: https://www.postman.com/mtnateam/workspace/docu-mentor