Extend API support fo Postman Documentor

[zman81988]

Is your feature request related to a problem? Please describe. Currently, Postman APIs do not provide a way to manage public documentation. Publishing and unpublishing documentation is a manual step.

Describe the solution you'd like Implement Postman APIs to manage documenter as well, with API endpoints to publish and unpublish a collection's documentation.

Describe alternatives you've considered None

Additional context We are working updating all of our APIs to be conformant with the OpenAPI/Swagger spec. One of the things we are most excited about that is the ability to easily allow our developers to leverage Postman to learn and use these APIs.

We'd like to make this as easy as possible for developers so we wanted to use the Run In Postman button. However, we'll be revving this enough that we'd like to be able to get from the swagger spec to a published Postman collection without manual intervention.

I'll defer to the Postman team on the best way forward to this but I would love a publish flag on the import API so that in one call I could go from the swagger generated from our source code to a button I can display on our website allowing someone to immediately play with our APIs in the Postman interface.

[Raja-Simha]

@zman81988 If I understand you correctly, this is how your workflow looks like:

1. Generate/update swagger spec from source code
2. Import Swagger spec into Postman and create a collection/documentation
3. Publish the documentation with Run in Postman and you would like to automate this?

[zman81988]

Hey @Raja-Simha, Yup, that's exactly right. I see two ways this could work for us. One is to have a static collection Id and input that into the standard embed code you provide and use the Postman API to update that collection whenever the swagger spec is updated. This would be something like a github action to talk between the generated spec and the Postman API.

The other avenue I see is generating collections and publishing them on the fly. We could fire an API call from the our CMS anytime someone clicked a button to generate the postman collection on the fly based on our latest published spec. Then you could return the run in postman link that we can pass along to the user.

The end goal is to keep our postman collections up to date without having to edit information the CMS.

[radkrish91]

We have the exact same workflow. And would like to automate the publishing part. Can this be expedited?

[bzmw]

My documentation workflow right now:

1. Edit OpenAPI Schema
2. CI builds into Postman.json
3. CI updates our website with new version
4. CI update our open source github repo with a new version
5. CI updates our Postman collection
6. Manually Open up Postman app, navigate to collection, click "share", click "update link".

The final manual step is very frustrating, there are only 2 people in the company that know it well enough to do it, we've tried documenting it but there are just too many buttons and permissions to make it easy, so every merge someone pings our slack channel and says "Need someone to update Postman button."

Please fix this.

[jpoehnelt]

My documentation workflow right now:

1. Edit OpenAPI Schema
2. CI builds into Postman.json
3. CI updates our website with new version
4. CI update our open source github repo with a new version
5. CI updates our Postman collection
6. Manually Open up Postman app, navigate to collection, click "share", click "update link".

Same steps here 😞

[kings1990]

some plan about api of publish document?

[prupke2]

It looks like the new "Embed a live version" option announced last week solves this issue!

https://blog.postman.com/new-run-in-postman/