TL;DR: Command line program to expand YAML or JSON references in an OAS 3 specification and create tables for JSON body object parameters in the main POST description, YAMLFIX at github.com/XTRM-Solutions/yamlfix.
My company decided to use POSTMAN for our API documentation, but we quickly ran into two serious issues. The first was that our API has a fair number of complex nested objects, which we put into OAS. Problem: when Postman turned these into documentation, the nesting was too deep did not display the bodies correctly
Secondly, our API uses POST and JSON data in the request body almost exclusively — and Postman did not promote JSON body objects and parameters into first-class (or even third- class, such as other solution’s click-to-expand templates) documentation.
To deal with this, I wrote YAMLFIX, which expands out all the references. It also creates some simple tables for body parameters in the REQUEST and RESPONSE (“200” success) bodies, which it then appends to the main body’s description.
This allows all documentation to be held with the API definition, and requires minimal manual intervention to update the documentation. Edit file, transform, import to Postman, create a collection, add static text, publish. Still too many manual steps there, but it’s not something I touch often enough to make further automation worth the time. Yet.
This resolved my pain, and I post about it in the vague hope it may be useful to someone else.
