Postman collection format

[HipZena]

It would be nice if the converter can support the postman collection format as well since I am not aware of any way to export to Swagger spec (2.0) from Postman.

[IvanGoncharov]

@HipZena Thank you for suggestion. It's definitely worth to implement feature. Do you have link to formal specification of this format? Also it's looks like postman have multiply versions of their format, which one are you interested in?

And as always if somebody wants to step up and implement this feature we will gladly accept PR.

[HipZena]

Thanks for the prompt reply. I do not have links to their spec (postman collection) and I'm not sure if they publicly publish one.

And yes, I'm aware of the fact that they've multiple versions. I just exported a postman collection from Postman but couldn't find any version information in the JSON file.

I would suggest you contact them to show them the good work you guys have done and see if they're willing to provide you the official specification.

[czardoz]

We do have a public specification (and a JSON schema): schema.getpostman.com

While we do have two versions of the specification, we also have https://www.npmjs.com/package/postman-collection-transformer which can interconvert between the two. (I will update the readme tomorrow!).

@IvanGoncharov, apologies, I haven't been able to be more active in this project :(

[IvanGoncharov]

We do have a public specification (and a JSON schema): schema.getpostman.com

@czardoz Thank you for link, it really helpful. Which version is currently used in Postman?

I played with postman collection and couldn't find format version inside. I reviewed specs and closes thing that I found is schema field. But Postman doesn't fill it currently. Am I right?

P.S. Can you please consider adding standard $schema field in new versions of Postman.

[czardoz]

@IvanGoncharov Postman currently uses v1.0.0

You're right, currently we don't embed version information in the Collection file. We will start embedding it in the upcoming version (v2.0.0). Example:

{
  "info": {
    "name": "HTTP Status Messages",
    "id": "my-collection-id",
    "_postman_schema": "https://schema.getpostman.com/json/collection/v2.0.0-draft.4/",
  },
  ... other stuff ...
}

The $schema field is present in our JSON schemas, https://schema.getpostman.com/json/collection/v2.0.0-draft.4/

[czardoz]

Oh, I will post some sample v1 and v2 collection here too :)

[IvanGoncharov]

@czardoz It will be very helpful. Thank you.

[HipZena]

Thanks @czardoz

[MikeRalphson]

@HipZena just a note that the APIMATIC API Transformer can convert Postman collections to various formats including Open API Spec / Swagger 2.0. The resultant file needs some hand editing though.

Edit: Just in case you had an urgent requirement.

[HipZena]

@MikeRalphson yes but we prefer open-source and the option to run it locally in our environment.

[restunited]

@HipZena Understood that you prefer open-source software. REST United also offers import via Postman collection format and then export to OpenAPI/Swagger spec 2.0.

We do plan to open-source our importer and exporter to facilitate conversion between different formats but not something with the highest priority at the moment (especially due to the fact that api-spec-converter is pretty good and becoming the de-facto standard for conversion between different formats)

[IvanGoncharov]

@restunited Biggest problems I see at the moment is companies building converters around their internal formats. It's totally natural decision for supporting multiple formats in the scope of one particular tool. But it limits reusability of such converters and require outside contributors to really understand internal format.

The fundamental difference is that we plan to use OpenAPI/Swagger as the intermediate format. Because of following reasons:

• It's popular format with developed community
• It very well documented
• No vendor lock for particular company
• It support vendor extension, so you can add info missing from core spec
• Many vendors provide open-source converters to/from their custom formats

[restunited]

@IvanGoncharov I can see api-spec-converter playing a more important role as a building block so that companies do not need to reinvent the wheel.

The question is more on how to push api-spec-converter to the next level to make it even more widely adopted.

[jacobscarter]

@IvanGoncharov any update on this? Consider making a PR to add the functionality unless you have already started on it and will be finished soon.

[IvanGoncharov]

@jacobscarter Didn't write any code for this issue. Do you plan to work on Postman2Swagger, Swagger2Postman or both?

[jacobscarter]

@IvanGoncharov swagger2postman already exists, so I will be building postman2swagger as a seperate npm module so it can be implemented the way you are implementing google-discovery-to-swagger, raml-to-swagger, etc.

[IvanGoncharov]

@jacobscarter Great. It exactly what I wanted to suggest 😄 BTW. Here is a good test suite of real-life postman collections: https://www.getpostman.com/integrations/run-button

[jacobscarter]

Yeah I'm very familiar with postman, I use their CLI tool Newman for all my automated API testing and what not. Ill let you know if I get stuck

[jacobscarter]

@HipZena @IvanGoncharov @czardoz I have some questions, I am curious what you guys think about them.

I am almost done with the converter, it was pretty straight forward, the things I am having trouble with is utilizing Swaggers Response Model and Response Statuses, I am considering trying to parse the tests for each Postman API call (if they exist) and try and gleam info from there about response models and statuses, what do you guys think? How high priority and and ideas on how to go about it.

[jacobscarter]

I have played around with node walking of the test js file with uglifyjs, there are too many problems with trying to actually run the JavaScript within the test js file because of unknown variables, etc.

[IvanGoncharov]

I have played around with node walking of the test js file with uglifyjs, there are too many problems with trying to actually run the JavaScript within the test js file because of unknown variables, etc.

@jacobscarter I also think parsing arbitrary JS is unreliable.

Just to be sure which version of Postman format you planning to support? v2?

If you have working prototype it would be great to integrate it with api-spec-converter. Don't forget to add couple test collection.

Next week I plan to add possibility to detect spec format and it can break some internal APIs. So it would be great to merge integration with Postman beforehand.

[jacobscarter]

@IvanGoncharov I'm working on getting it done ASAP, turns out to be pretty tedious :/ I'll keep you updated

[IvanGoncharov]

@jacobscarter No need to hurry. You can just publish whatever you have right now as 0.0.1. Then submit integration and mark Postman support as experimental in README.md. And continue to work on converter at your own pace.

[jacobscarter]

@IvanGoncharov first version is up, a lot of work do do but usable Swagger v2 JSON files are being generated. I'm hoping by tomorrow to have request body conversion done. Response body is a bit of a pipe dream so I'll tackle some other necessities before going back to that.

https://github.com/IntegrateDev/postman2swagger2

Now I need to get a PR to you for using it in api-spec-converter, hopefully can do that tomorrow

[rithvikvibhu]

Any update on this?