Postman integration into CI/CD pipline for creating and updating postman collections

[ducka]

I'm currently doing a lot of research for my company in how we can propagate API Documentation (via the Swagger/Open API Spec) from our Microservices to our API Gateway product (like Azure API Management) and our API Documentation product (like Readme.io). My aim is to do this in such a way that our publicly facing API Documentation is always kept up to date as new changes are deployed to the public via our CI/CD pipeline.

In addition to this it woud be great if we could also keep our shared team collections in Postman up to date with the latest API Definitions we publish. I'd also love to stick a "Run with postman" button in our ReadMe.io API Documentation that allows our customers to create collections based off our latest published API Definitions.

I don't know if this is at all possible with Postman as it stands. With my research to date I've not found any way to achieve this with postman in an automated way that I could integrate into a CI/CD pipeline.

[Raja-Simha]

Hi @ducka, thanks for writing to us.

We are aware of the need to keep collections and API documentation up to date by integrating with CI/CD pipeline. We are working on initiatives to help resolve this need. Could you please take some time to help us understand how you 'currently' manage your workflow, specifically, how do you ensure that your API documentation is up to date with any new changes deployed to production? Understanding your workflow will help us design a better experience around the solution.

[sankalp0o]

@ducka We allow generation of collection from OpenAPI specifications via an API call. What can be tricky is to create/update a Run in Postman button from the CI/CD pipeline. We've recently launched some features which allow you to save your specification in Postman and generate documentation from it. We're working on syncing the documentation when the schema changes, so it would definitely help with your problem in future.

How do you update your specification and documentation to keep up with the changing API?

[SimoTod]

HI @Raja-Simha and @sankalp0o

Not sure if this is the right thread, but I don't want to create duplicates, let me know if you want me to create a new ticket, please.

We are facing a similar challenge in my organisation: we have set up a CI/CD pipeline so when we update the openapi schema in our repository and the build passes, the pipeline automatically updates the relevant API version in postman.

I know that it's possible to generate a documentation for the api using the generate collection button but, once generated, the documentation doesn't seem to keep up to date when a changes is introduced on the api schema.

I assume this is an expected behaviour to avoid that the wrong documentation would go public by mistake.

Our documentation is private, it's consumed by other teams to build different components and our APIs are still in development. We build them iterating in sprints so data contract are subjected to amendment and the schema changes almost daily.

Although part of the update is done by the CI/CD pipeline, we are forced to go into postman, generate a new documentation and delete the old one when we want to update it.

Are there any plans to create documentation that auto-updates or add some sort of update documentation button (and ideally an endpoint for it so we can call it from our pipeline)?

Thanks

[sankalp0o]

Hey @SimoTod , We're trying to do auto-update the documentation on schema update. You should see them soon!

I have one question for you, do you add anything to the documentation after generating it from schema or do you use it as is?

[SimoTod]

Thanks @sankalp0o At the moment, I use it as it is. I assume it would be a nightmare to have the autoupdate and keep any existing changes so I don't expect it to happen. It would be good if the documentation could show the possible responses in the central column (with the type hinted parameter) and use the example values in the right column but I'm not precious about it. :)

[adritabhor]

@sankalp0o - heard the same use case for another enterprise company today.

[andmoredev]

@sankalp0o @Raja-Simha We are facing a similar issue. And we are forced to have manual steps to get the documentation updated. We don't expect to update the documentation after it is generated since we really want this to be automated and that will get overriden. To avoid this issue we plan to make use of the 'description' attributes in OpenAPI that can contain Markdown so this way most of our documentation can be self maintained by a file (OpenAPI3 definition) that is needed for development purposes as well since we are using this file as well to generate our API request validations in AWS.

This feature will really improve our full pipeline so that our documentation never falls behind of what has been deployed.

[karthiks3000]

+1 for this. The only thing stopping us from using postman across the board is that the documentation can't be self hosted and auto-updated by a jenkins job

[nwhatt]

I'm not sure if this the same issue - but I'd love to not have to click this button to "publish" or "share" a collection.

I can use the management API to update collections no problem - but I can't find a way to "share" via API.

[ajcastro]

This is related to what I am trying to achieve. https://github.com/postmanlabs/postman-app-support/issues/10823

[ajcastro]

@sankalp0o @SimoTod @andmoredev How did you work around this issue at the moment?

[SimoTod]

@ajcastro I didn't and I stopped looking into it eventually

[ajcastro]

@SimoTod how is your workflow now?