API Documentation Workflow

Hello!

I'm curious if anyone has an API documentation workflow they are willing to share that includes the Postman tool for publishing.

I'd like a workflow that works as smoothly as possible with minimal mandatory manual steps. Currently I'm familiar with the Swagger toolchain for automatically generating OpenAPI specification, and I know that you can then import that into Postman as a collection.

From there we can use additional functionality that Postman offers like writing tests, adding extra examples, using environments etc.

One concern is that reimporting the OpenAPI specification if you make a change to the service 's API may overwrite the extra functionality.

​

1. What's your workflow like?
2. How do you structure Postman across the org? I'm thinking a workspace per team, with each team owning a collection for each service in their jurisdiction.

​

Would really appreciate any thoughts or discussion; thanks in advance!