[Feature Request] Swagger (OpenAPI) import

[andrioid]

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]

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]

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

[andrioid]

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]

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 (https://github.com/luckymarmot/API-Flow/pull/136).

[andrioid]

Whatever works 👍

[kzap]

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]

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]

It would be great to have this feature.

[hexpunk]

https://github.com/getinsomnia/importers/issues/14

[HartS]

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[bot]]

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.

[jcgruenhage]

@stale don't you dare closing this.

[gschier]

I won't let it close!

[gschier]

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

[slawus]

I've just created PR containing swagger 2.0 importer here https://github.com/getinsomnia/insomnia/pull/695. Feel free to check it out and share your thoughts.

[audvin]

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]

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

[audvin]

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

[ashleydw]

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]

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]

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 https://github.com/postmanlabs/postman-app-support/issues/3390).

[bugproof]

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.

[oleg-codaio]

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]

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?

https://github.com/getinsomnia/insomnia/blob/8a751883f893437c5228eb266f3ec3a58e4a53c8/packages/insomnia-importers/src/importers/swagger2.js#L1-L18

[oleg-codaio]

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]

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]

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

[oleg-codaio]

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]

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

[kodekraft]

@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.

[ThaDaVos]

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]

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]

@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]

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]

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]

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]

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

[audvin]

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]

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

[audvin]

@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]

@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]

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