Support for swagger v3.0.0/OpenAPI

[dancrumb]

App Details:

Postman for Chrome
Version 5.1.3
OS X / x86-64
Chrome 60.0.3112.90

Feature Request

Currently, Swagger import is limited to v1 and v2 of the swagger schema.

With the release of swagger v3.0.0, AKA OpenAPI, is support for this on the roadmap?

[stellis]

@rdkls Thanks for sharing this, but it's not going to solve the problem for some of us.

v3 has features that can't be converted back down to v2 losslessly. One example is anyOf.

I recently tried a v3-to-Postman converter and the results were a disaster. There were response headers moved into the request parameters, among many other inaccuracies.

There are tons of libraries Postman could use if they wanted to support v3. It's baffling and user-unfriendly that they haven't already.

[a85]

Everyone, We are testing out OpenAPI 3 support in our Canary builds (getpostman.com/canary). It might not be perfect but help us test it out! We are also building a plug-in model that will help us update OpenAPI and schema support independently of releasing a new version of the app. The development of the plug-in system is what has resulted in seemingly no visible progress on this but we see that as an essential part to support OpenAPI and other schema formats in Postman. Eventually, it got pretty taxing for the team to support the variety of importers/exporters in line with our development process.

[philsturgeon]

Amazing! Thank you so much.

Totally understandable that building an entire add on system slowed you down. If a similar situation pops up maybe you could post a link to an issue for “Add-on System” and folks could follow that progress, then folks know what you’re up to and don’t feel like they’re being ignored. :)

I’ll check it out soon. Thanks again!

[luketlancaster]

Just tried the import OpenAPI 3 situation, and it worked really well! Our docs are only so good (and I'm personally only the tiniest bit knowledgeable about all of this 😬), as we're getting things converted over, but it's a great start. Thanks for working on it!

[a85]

@philsturgeon Thanks! I agree with the suggestion. We are getting better at managing the tracker in general but it's hard for to deal with the volume of comments + issues (all great feedback of course). The team will update other threads too. Lots coming up in 2019.

[markmooibroek]

Good to hear this is actively worked on! Tested the function with the Canary build, but got an undefined error. Maybe you can improve things with my json file. Good luck!

open_api_3_test.json.txt

[SamvelRaja]

@markmooibroek Thanks for providing the Test file. We could reproduce the issue. We shall update this thread once it gets fixed from our end.

[derrickmehaffy]

@SamvelRaja I am also getting an undefined error, I do have a bit of redocs x-data stuff in mine as well, your welcome to use it as a test case also: (Warning it is quite large and it is very possible that it could be user error 😛 ) https://github.com/canonn-science/CAPIv2-Strapi/blob/development/public/openapi.yaml

[SamvelRaja]

@derrickmehaffy Thanks for providing the test case JSON.

[patthiel]

@SamvelRaja I experienced the same error as @markmooibroek while attempting to import our OpenAPI 3 spec. In case you need another 10000+ line spec to reproduce from 😄:

https://developers.linode.com/api/v4/openapi.yaml

[abhijitkane]

@patthiel @derrickmehaffy - Your specs should import in the latest version of Postman Canary - 6.6.0-canary02 @markmooibroek - Your spec should import as well. We're tracking an issue where example URLs for requests with path variables in the URL aren't being imported correctly, and we expect a fix to be out in a few days. - https://github.com/postmanlabs/postman-collection/issues/740

[jcstanaway]

6,6,0-canary02 appears to have an issue with forward references. I had a $ref to an element defined later in the file and the import failed with an error that it couldn't find that referenced element. I moved things around so that the element was before the reference and the import succeeded.

I can't post the spec due to proprietary reasons, but if needed I can try to mock something up.

[abhijitkane]

@ccs018 Odd - we look through all components before constructing the requests. An example OAS spec would help.

[jcstanaway]

I'll try to put a sample spec, but might take a couple days before I can do that. Note that this was within the components section - an element in the components $ref'ed to something later within the components.

[abhijitkane]

@ccs018 I'm able to import the JSON at https://gist.github.com/abhijitkane/9ca56ec40bc2668107b85ce92d4f402a with the properly generated response. The Pet schema is referenced in, but defined after Pets.

[Ryandaydev]

Checked canary build against a working OpenAPI spec, and it imported successfully and requests worked.

[zmes50416]

Tried the canary03 version, import working really well! But I got one issue that server template variable is not parsing correctly.

According to openAPI 3 document here, It does support server templating. Can Postman parse it as the Environment variable? Ex:

server:
  - url: http://{host}:{port}
    variables:
      - host:
      - port:

request should be parsed ashttp://{{host}}:{{port}}/what/every/your/api instead it is been parsing as http://{host}:{port}/what/every/your/api

For now I am manually modifying it. It is workable in short term, but an auto parsing when importing will be a lot helpful!

Neverthelast, thank you guys for support OpenAPI, It really help me a lot.

[mm-matthias]

Are OpenAPI files with $refs to other files supported yet? I've got something looking like:

api.yaml:

paths:
  /somepath/:
    get:
      operationId: someoperation
      summary: bla
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: 'models.yml#/components/schemas/some-model'

And the models.yml contains the corresponding schema.

When I add api.yaml in Postman's "Import files" section, the importer will complains

Error while importing Open API 3.0: ref models.yml#/components/schemas/some-model not found.

When I try to use the "import folder" option (all my .yml files are in that folder), nothing happens.

Is this scenario supposed to work?

EDIT: Hmm, it does seem to work with a different file that referencs other .yamls. So the message is probably misleading, I guess there is some exception down the line when processing one of the files and this exception is not carried upwards to the message?!

[mm-matthias]

Do you have any plans to add generation/editing of request bodies with OpenAPI 3.0? Having only the urls and query params doesn't really address our needs as all the meat is in the request body.

[philsturgeon]

Entirely agree that request bodies and example requests / responses should be built up using the OpenAPI Schema provided for that request/response.

[abhijitkane]

@mm-matthias Could you share a sample spec? Right now, the importer generates a sample request body/example response body based on the schema (for form-data, urlencoded, and raw-JSON formats only). Are you using an XML schema?

[danfowler]

https://swagger.io/docs/specification/authentication/

After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively.

I've defined and applied a security scheme at the root level only, so I would expect each endpoint of the imported collection have an Authorization of type "Inherit auth from parent". Instead, after importing a new collection from my OpenAPI file, each endpoint's Authorization is set to Basic Auth. This is inconvenient, because I then have to manually set each endpoint to inherit its authorization.

I think setting the root level OpenAPI authorization as the Collection authorization (currently, it's "No Auth") and defaulting the endpoint Authorization type to "inherit auth from parent" would be ideal as that is the expected behavior of OpenAPI.

[abhijitkane]

@mm-matthias @philsturgeon We've open-sourced the converter at https://github.com/postmanlabs/openapi-to-postman. The current Postman Canary uses 0.0.7.

We've added basic support for generating XML request/response bodies too - this should show up in the next Canary release.

@danfowler Agreed - will work on this.

[a85]

Thank you for your patience everyone. Closing this issue now. If you have comments/suggestions/bug reports for the feature please file it in the repo that @abhijitkane linked to. We'll be soon rolling out the ability to update plug-ins without having to update the app and improvements to converters will ship much faster.