Quarterly API updates is an extremely tedious job with how Postman is built today

I have spent more than 4 hours in the attempt to perform an update of Postman collection with valid OpenAPI 3.0 JSON file after quarterly release of one of our APIs. It seems like Postman does not consider updating existing schema definitions and sync-ing it with the documentation collection as a priority user scenario.

  • Importing the new schema and sync-ing via Postman does not work. Postman detects the change in schema, but fails to properly merge the new collection based off the new schema definition into the existing collection. This means you have to delete a version and make people who forked the repo visit the page and fork again. Which brings me to the next point.
  • Importing the new collection is not either: The nesting level limitation doesn’t allow me to generate documentation within the Postman tool without producing “Error too many nested levels error”. This brings me to the next point
  • openapi2postmanv2 seem to be in the need of update - it fails with “Error Error: Expected a regexp or string in /properties/entries/items/0/properties/product”. Swagger validates the OpenApi spec perfectly.
    -Postman has this blog- Sync Your Specs | Postman Blog which is terribly out of date. The common error can be filtered out with some research. But then it seems like swagger2-postman2-converter is not up-to-date. If you use these tools, after all the workarounds to make it work, you will have a broken collection in production.

All in all, I’m having a very average and unimpressive experience with updating Postman definitions and I’d like to hear how users in this community solve their issues despite all the limitations present.

Hey @omarkhazamov ,

Are you able to share that spec here? It would help looking into the blockers you’re facing. If you’d rather not share publicly you can send it to me directly on arlemi@postman.com.