Allow generating Additional Types of Postman Collections

[gregra81]

When trying to generate a collection in Postman UI, there are a few options that can applied on a collection:

These options also align with Postman RESTful APIs, for example - generating a mock on a collection: https://www.postman.com/postman/workspace/postman-public-workspace/request/12959542-296628ed-d49b-4206-b4a7-d622e693945c

It will be great if Portman will support those different options when generating a collection:

1. API Docs collection
2. Mock collection
3. Monitoring collection

[thim81]

@gregra81 Portman currently generates "Collection", based on an OpenAPI document and inject contract/variation tests based on the OpenAPI specifiction, mainly for facilitating API testing & a API playground to kick-start API users.

The API docs collection injects OpenAPI document made available in Postman. The mock collection & Monitor collection, is based on the "collection", so technically it would be possible since Portman leverages the Postman API to insert/update the Postman collection.

What would be your use-case to have the other collection types insert by Portman?

[gregra81]

The way we facilitate the Design (API) First methodology in Bizzabo is by working from the Github repository and integrating our CI (in CircleCI) with Postman (we have a paid account). Our flow is:

• We have an OAS YAML file in each Github repo that describes the API of the service
• New API design is done through a PR
• Whenever a new feature that requires an API change needs to be built, a new PR is opened in the repo and the diff link is being shared within the technical design document
• The above PR also creates (or updates) a new API in Postman, including a version and a schema
• At this point, we want to create a collection from this API, upload it to Postman, and create a bunch of relations between the above API version and the collection we created, specifically documentation and mock relations
• Other potential steps obviously include generating the tests and running them as part of the CI (also maybe generating the monitors on Postman too). All of these steps are a mix of Portman functionality and Postman APIs

What this workflow achieves is having the initial API design available for client developers to consume (docs + mock).

At this point, Portman generates a collection from an API spec, injects tests, and can sync the collection to Postman (which is huge obviously), and we're missing the other steps. The dream is that Portman will be able to achieve the above workflow end to end, instead of me building a new CLI

Thoughts?

[Gdewilde]

Thanks for the context @gregra81! Impressive flow

[gregra81]

@Gdewilde I can happily work on such a flow within this repo if you're ok with that. Specifically, I suggest implementing another command that can upload an OAS file to Postman and link a generated collection to it

[thim81]

@gregra81 In essence adding the Postman API operations to link the collection as an API or Mock, would not be the biggest complexity.

The configuration management to keep it simple and logically would be the difficult part. Adding a CLI configuration parameter (https://github.com/apideck-libraries/portman#cli-usage) would be the tricky part.

Do you have any suggestions? @nicklloyd What do you think from a configuration point of view?

[gregra81]

@thim81 Looking into the existing config file I can suggest the following additions:

• uploadApiToPostman - creates or updates the API, creates or updates the version, creates or updates the schema
• withDocs - creates a relation of type "docs" between API and the generated collection
• withMock - creates a relation of type "mock" between API and the generated collection

[nicklloyd]

Wondering if these could all fall under something like postmanApiOptions.

So something like:

postmanApiOptions: {
  withDocs: true,
  withMock: {
    ...mockOptions,
  },
  withMonitor: {
    ...monitoringOptions
  }
}

I'm a bit unclear on if the 'uploadApi' bit requires config or we can use the schema Portman has it's hands on already, and the presence of postmanApiOptions implies we upload it as an API.

Have to admit I'm a bit unclear on how the documentation works outside the spec, or it it's just a matter of pointing postman to the spec to create the relation....

[gregra81]

@nicklloyd Agree on being implicit with postmanApiOptions, which can also include stuff that is now in postmanConfigFile and the syncPostman param (though this requires deprecation of the current parameters set).

The way docs work (from what I saw), is that you generate a collection and then create a documentation relation. The same applies to other types of Postman functionality (mocks, test suites, contract tests, etc)