Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature Request] Swagger (OpenAPI) import #281

Closed
andrioid opened this issue Jun 2, 2017 · 42 comments

Comments

@andrioid
Copy link

commented Jun 2, 2017

It would really take the client to a whole new level, if I could point it at a Swagger definition file, and it would import all the resources into my environment.

A feature worth paying for, I might add.

@nedy13

This comment has been minimized.

Copy link

commented Jun 2, 2017

I have to admit that I have not used insomnia yet. I want to try it out with our REST services, but we only provide a Swagger definition. I would really appreciate this feature.

@dmlittle

This comment has been minimized.

Copy link
Contributor

commented Jun 3, 2017

@andrioid could you post an example of a Swagger definition file?

@andrioid

This comment has been minimized.

Copy link
Author

commented Jun 3, 2017

By a quick look at the codebase, I'm fairly certain that you could use SwaggerJS (https://github.com/swagger-api/swagger-js) to integrate with Swagger. Their current branch doesn't work with our older Swagger definition (frameworks, meh) though. But it would be a cool feature, regardless of me being able to use it, or not.

OpenAPI is here: https://github.com/OAI/OpenAPI-Specification
Swagger has a bunch of tools on their site: http://swagger.io/

We use Restler (PHP framework) at my place of employment. It uses v1.1 of Swagger, while I believe OpenAPI is using v2.

Example: http://editor.swagger.io/#/

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Jun 3, 2017

I'm not sure swagger-js would solve this issue. The main problem is parsing and converting the Swagger definition into the Insomnia data format. Paw is currently working on a project to help convert API definition standards back and forth, and I have been working on a PR for (luckymarmot/API-Flow#136).

@andrioid

This comment has been minimized.

Copy link
Author

commented Jun 3, 2017

Whatever works 👍

@gschier gschier changed the title Feature request: Swagger (OpenAPI) import [Feature Request] Swagger (OpenAPI) import Jun 7, 2017

@kzap

This comment has been minimized.

Copy link

commented Jun 20, 2017

I think API flow would work great, for both importing and exporting formats so one could choose their client and export to another format for productions or sharing with others

@MALPI

This comment has been minimized.

Copy link

commented Aug 24, 2017

Same here as @nedy13. I didn't use insomnia yet but am keen on doing so. Still we are documenting all our services with swagger. As long as this isn't supported I cannot give it a try.

@thatsmeta

This comment has been minimized.

Copy link

commented Oct 10, 2017

It would be great to have this feature.

@JayAndCatchFire

This comment has been minimized.

@HartS

This comment has been minimized.

Copy link

commented Oct 24, 2017

Now that Swagger has become openAPI I think this is even more important. Would it be possible to store the API data as swagger natively? If not, export as swagger is a much-needed feature as well.

@stale

This comment has been minimized.

Copy link

commented Dec 23, 2017

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

@stale stale bot added the Stale label Dec 23, 2017

@jcgruenhage

This comment has been minimized.

Copy link

commented Dec 24, 2017

@Stale don't you dare closing this.

@stale stale bot removed the Stale label Dec 24, 2017

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Dec 24, 2017

I won't let it close!

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Dec 24, 2017

There, now @Stale will ignore it with that label 😀

@slawus

This comment has been minimized.

Copy link
Contributor

commented Jan 10, 2018

I've just created PR containing swagger 2.0 importer here #695. Feel free to check it out and share your thoughts.

@audvin

This comment has been minimized.

Copy link

commented Feb 7, 2018

I get No importers found for file when trying https://api.symplur.com/v1/openapi.json with Insomnia 5.14.6. Any guidance on this?

@slawus

This comment has been minimized.

Copy link
Contributor

commented Feb 7, 2018

@audvin For now, this plugin supports only Swagger 2.0 format. Your specfication is written in 3.0.0.

@audvin

This comment has been minimized.

Copy link

commented Feb 9, 2018

That makes sense. I guess we're on OpenAPI 3.0.0

@ashleydw

This comment has been minimized.

Copy link

commented Feb 13, 2018

The importer fails if a parameter type is object (generated from https://github.com/mulesoft/oas-raml-converter):

{
  "swagger": "2.0",
  "info": {
    "title": "Api",
    "description": "",
    "version": "v1"
  },
  "x-basePath": "/api/{version}/Api",
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/{id}": {
      "parameters": [
        {
          "description": "A NUMBER OR STRING",
          "type": "object",
          "in": "path",
          "name": "id",
          "required": true
        }
      ]
    }
  }
}

Change the type to string and it works correctly.

@slawus

This comment has been minimized.

Copy link
Contributor

commented Feb 22, 2018

Hi!

First of all, this example is not valid swagger file. There are at least few problems:

  • http method missing in endpoint definition
  • you can NOT use object as type of path parameters (specification)
  • responses field missing in Path Item Object

...so at the first glance it's not a suprise that it doesnt work. However, I've fixed you example, and find out it still doesnt work.

Here is my input:

{
  "swagger": "2.0",
  "info": {
    "title": "Api",
    "description": "",
    "version": "v1"
  },
  "x-basePath": "/api/{version}/Api",
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/{id}": {
      "get": {
        "parameters": [
          {
            "description": "A NUMBER OR STRING",
            "type": "string",
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "description": "THIS IS AN EXAMPLE OF OBJECT TYPE PROPERTY",
            "schema": {
              "type": "object"
            },
            "in": "body",
            "name": "body",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request"
          }
        }
      }
    }
  }
}

I'am almost 100% sure it's caused by lack of object parameter's properties definition. I was convinced that this obligatory when using object type parameters, but after second check I know i was wrong. The fix is needed. Till now you can partiali omit the bug by adding "properties": {} to all object type parameters. Working example:

{
  "swagger": "2.0",
  "info": {
    "title": "Api",
    "description": "",
    "version": "v1"
  },
  "x-basePath": "/api/{version}/Api",
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/{id}": {
      "get": {
        "parameters": [
          {
            "description": "A NUMBER OR STRING",
            "type": "string",
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "description": "THIS IS AN EXAMPLE OF OBJECT TYPE PROPERTY",
            "schema": {
              "type": "object",
              "properties": {}
            },
            "in": "body",
            "name": "body",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request"
          }
        }
      }
    }
  }
}
@stianlagstad

This comment has been minimized.

Copy link

commented May 2, 2018

Any plans on supporting OpenApi v3? There are a lot of people ready to jump over from Postman if support for openapi v3 is added (see postmanlabs/postman-app-support#3390).

@0xNOP

This comment has been minimized.

Copy link

commented Jun 28, 2018

I have 2.0 spec generated with Swashbuckle.AspNetCore but I get "No importers found for file". It should work pretty much like swagger-ui and it would be perfect. What would be even more awesome is auto re-importing the spec when it changes(like a watch) that would be heaven.

@vaskevich

This comment has been minimized.

Copy link

commented Jun 29, 2018

Yeah, I'm running into the same issue even with Swagger 2.0. I used api-spec-converter to convert our spec, and swagger-parser says it's a valid Swagger 2.0 spec. But Insomnia gives a "No importers found for file" error.

Would be nice if Insomnia actually logged what it didn't like about the imported schema, or ignored non-fatal errors.

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Jun 29, 2018

Hmm, I'm not familiar with Swagger but here's the code to validate an imported document (it's very simple). Can you spot what the problem might be?

const SwaggerParser = require('swagger-parser');
const SUPPORTED_SWAGGER_VERSION = '2.0';
const MIMETYPE_JSON = 'application/json';
const SUPPORTED_MIME_TYPES = [MIMETYPE_JSON];
const WORKSPACE_ID = '__WORKSPACE_1__';
module.exports.id = 'swagger2';
module.exports.name = 'Swagger 2.0';
module.exports.description =
'Importer for Swagger 2.0 specification (json/yaml)';
module.exports.convert = async function(rawData) {
// Validate
const api = await parseDocument(rawData);
if (!api || api.swagger !== SUPPORTED_SWAGGER_VERSION) {
return null;
}

@vaskevich

This comment has been minimized.

Copy link

commented Jun 29, 2018

Well, the good thing is that you're using swagger-parser, too (though perhaps you should update from v4.0.1 to the recently-released version 5.0.0 [which supports OpenAPI 3.0!]).

That being said, instead of eating thrown errors and just returning null in parseDocument(), can you log the error somewhere and show it in the UI (or even some log file)? Otherwise it's hard to know what exactly went wrong.

I think you should be able to check for the top-level "swagger" property in the loaded file, which should tell you that the file is a Swagger file to be imported, and then if parsing fails you can throw an exception with the details. Should be an easy-enough change, but I'm not familiar enough with this repo to make it.

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Jun 29, 2018

That's what the above snippet is doing (you may need to scroll down in it). It checks if api.swagger === '2.0'.

   if (!api || api.swagger !== SUPPORTED_SWAGGER_VERSION) { 
     return null; 
   } 

It's tricky to display the errors because the importer could get any file type. For example, if the user imports a regular insomnia.json file, the Swagger will fail (because it's not Swagger) but the user should not be made aware of that.

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Jun 29, 2018

Perhaps giving the user the ability to see the logs from each parser, more for debugging purposes, would be useful.

@vaskevich

This comment has been minimized.

Copy link

commented Jun 29, 2018

Ehr, what the code is doing now is:

  const api = await parseDocument(rawData);
  if (!api || api.swagger !== SUPPORTED_SWAGGER_VERSION) {
    return null;
  }

I was proposing instead doing something like:

    const rawJson =
      unthrowableParseJson(rawData) || unthrowableSwaggerParser_YAML_parse(rawData);
    if (!rawJson.swagger) {
      return null;
    }
    
    try {
      assert.equal(rawJson.swagger, SUPPORTED_SWAGGER_VERSION, 'Only 2.0 is supported');
      const api = parseDocument(rawJson);
    } catch (err) {
      log(err);  // If we got here, this was a Swagger doc but has some validation error.
    }

That way if the JSON/YAML is at least valid and looks like a Swagger spec, it would get interpreted as such (and not under any other parsers). Not sure how easy it is to wire that message up to the UX but at least logging the error would help folks debug the issue.

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Jun 29, 2018

Oh that makes sense. Great idea! I'll see if I can get that into the next release

@kodekraft

This comment has been minimized.

Copy link

commented Jul 15, 2018

@gschier , i've looked through the branches and have not seen this fix implemented anywhere. Has this been de-prioritized? It's frustrating not conveniently having access to what is wrong with the swagger doc (especially if the swagger linter says its valid). Thanks.

@dvdbot

This comment has been minimized.

Copy link

commented Sep 6, 2018

What's the progress on the support for Swagger/OpenAPI 3?
Currently trying to import my ASP.NET Core NSwag and getting a "No importers found" error

@trinary

This comment has been minimized.

Copy link

commented Nov 6, 2018

Is there any way to help get OpenAPI 3 support going? I forked the project and did a very simple/hacky addition to the importers that updates swagger-importer and fills out the basics using most of the same code as the current swagger2 stuff: https://github.com/trinary/insomnia/tree/openapi3 It works, but someone who knows the codebase better can certainly do a cleaner/more complete job.

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Nov 6, 2018

@trinary your branch doesn't look hacky to me. As long as it works. If you added some test cases I'd be happy to merge it.

Some support is better than no support for this sort of thing, then the community can help improve it later as needed 😄

@trinary

This comment has been minimized.

Copy link

commented Nov 8, 2018

Great, I'll get it in shape to be merged soon. I'm duplicating a bunch of stuff from the swagger2 importer (which honestly should become redundant if we utilize swagger-importer v6.x properly, it handles both) , do you want me to try to extract that code?

@philsturgeon

This comment has been minimized.

Copy link

commented Nov 26, 2018

Awesome work folks! Btw it's not called Swagger anymore and hasn't been for a while. Let's just call it "OpenAPI" from now on, regardless of v2 or v3. Old tooling has old names but new tooling should use new name! 🤓

@ridhoq

This comment has been minimized.

Copy link

commented Jan 9, 2019

When I try to import my Swagger 2.0 document, I get the following error in the DevTools: Failed to import data RangeError: Maximum call stack size exceeded. It's a fairly large document weighing in at around 1.1 MB. Any ideas?

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Feb 7, 2019

Ah, this was done a while ago. Please report any problems as new issues

@audvin

This comment has been minimized.

Copy link

commented Feb 13, 2019

Sorry, how do I import data from OpenAPI?

I just tried an import from OpenAPI json url and got "no importers found for file"?

@sroettering

This comment has been minimized.

Copy link

commented Feb 15, 2019

@trinary It would be awesome to have your openapi3 importer in insomnia! Are you still on it?

@audvin

This comment has been minimized.

Copy link

commented Mar 13, 2019

@gschier Can you confirm if Insomnia actually supports OpenAPI import?

I see this issue as closed and accepted, but when I try to import OpenAPI I get no importers found for file.

@michaeljmcd

This comment has been minimized.

Copy link

commented Mar 15, 2019

@audvin - I noticed that Open API v2 JSON worked, but Open API 3 JSON or YAML did not. Wasn't too big a deal to me because the API I am using is fronted by an API gateway that supports all three, but it is a caveat of which to be aware.

@audvin

This comment has been minimized.

Copy link

commented Mar 18, 2019

Should I open a feature request for Open API 3 support?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
You can’t perform that action at this time.