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/swagger2 importer #695

Merged
merged 6 commits into from Jan 16, 2018
Merged

Conversation

@slawus
Copy link
Contributor

slawus commented Jan 10, 2018

Swagger 2.0 importer

Hi! I'm super happy to share with you first version of swagger (aka OpenAPI) importer implementation. For now it supports only swagger version 2.0 (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md). It handles both with .yaml and .json files.

What it does?

Creates requests based on endpoints definitions in swagger file. My goal was to do that in the most usefull way, in the same time keeping it simple so it does not force users use model that does not dit their way of work.

  • if defined, summary is used as name of the request. Otherwise, it's "METHOD /path".
  • replaces parameters in request paths with variables e.g. /foo/:bar becomes /foo/{{ bar }}. This easies request chaining a lot.
  • set's body mimeType.
  • (if application/json mimetype is supported by API) fills body of the request with example value. If parameterSchema.example or parameterSchema.default are not defined, it will generate value based on parameterSchema.type field.
  • imports all query & header parameters, and fills them with example values (as described above). Non required parameters are turned off by default (you can turn them on manually), yet still visible.

... what's more:

  • creates new workspace with base environment, defining base_url as "{{ scheme }}://{{ host }}{{ base_path }}"
  • creates environment with variables from swagger specification
    json { "base_path": "/v2" # swagger.basePath, "host": "petstore.swagger.io" # swagger.host, "scheme": "http" # swagger.schemes[0] }

Important notes

  • It can't process files containing external references (i.e. to other files) due to importer's interface enforced by Insomnia App. Importers get just content of the file, not the path itself, so it's impossible to figure out where the external files are kept. In this case, you have to use external tool to dereference source file first (eg. https://github.com/BigstickCarpet/swagger-cli)

Dependecies

This PR heavily depend on my other PR - Async importers (#694). Under the hood, the importer uses https://github.com/BigstickCarpet/swagger-cli for specification dereferencing. This library is asynchronous, which makes the importer is also asynchronous.

Final thoughts

I'm very fresh user of Insomnia, so I'm not sure if my approach is correct. If you have any suggestions, feel free to share!

slawus added 4 commits Dec 27, 2017
… endpoints from swagger 2.0 specifications. Supports query params, headers and body. Mocks body of application/json endpoitns
@eMerzh

This comment has been minimized.

Copy link

eMerzh commented Jan 12, 2018

nice 👍 i also had a POC where i took the first tag as a folder. what do you think about it ?

@slawus

This comment has been minimized.

Copy link
Contributor Author

slawus commented Jan 12, 2018

This is actually feature I wanted to implement since the beggining, however I'm not sure if this is something most of the users would like to use. In case of simple APIs this additional structure would probably add some clarity, however in case of complex interfaces it may have opposite result, as we are using only first tag.

Imagine endpoint POST /users/:id/pets, with tags: ['user', 'pet']. It's clear that most relevant tag is "pet", however we can't force users to make it "first tag". After import, user might be looking for the request in one folder, while it's in another.

I also thought about other solution, where we create copy of a request for each tag, so if endpoint has multiple tags, it is available in every related folder (this is how swagger-ui works). But there would be a side effect - if there was a need to update request, user would need to update each of them separately.

I'm more than happy to add "request groups", let's just wait for other opinions, to figure out what would be most beneficial for everyone :) Thanks for you feedback!

Copy link
Contributor

gschier left a comment

This is beautiful, great work! I don't know anything about Swagger, but this seems like a good approach based on your PR description.

gschier added 2 commits Jan 16, 2018
@gschier gschier merged commit e987931 into Kong:develop Jan 16, 2018
1 of 2 checks passed
1 of 2 checks passed
continuous-integration/travis-ci/pr The Travis CI build is in progress
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
@IVIyg0t

This comment has been minimized.

Copy link

IVIyg0t commented Feb 22, 2018

I keep getting "No Importers Found" when I input a URL to a swagger 2.0 JSON definition. Is any one else having this issue?

@slawus

This comment has been minimized.

Copy link
Contributor Author

slawus commented Feb 22, 2018

@IVIyg0t there is actually one known bug in the importer, that might be the reason. It's described in #281

Can you provide the input, so I can debug what's wrong in your case?

@ChaseVoid

This comment has been minimized.

Copy link

ChaseVoid commented Mar 14, 2018

@slawus I get the same issue when I import REST API for Oracle Eloqua Marketing Cloud Service in Version 5.14.9 (5.14.9.1895)

@bugproof

This comment has been minimized.

Copy link

bugproof commented May 14, 2018

@slawus I have the same issue as @IVIyg0t . "No importers found" when trying to import .json 2.0 specification. It would be so great to have something like auto synchronization of OpenAPI spec with insomnia so I could use it instead of Swagger-UI

@cooleiwhistles

This comment has been minimized.

Copy link

cooleiwhistles commented May 1, 2019

Any update for the "No importers found" issue?

@gschier

This comment has been minimized.

Copy link
Contributor

gschier commented May 2, 2019

Yes #1354

Sent with GitHawk

luizmariz pushed a commit to luizmariz/insomnia that referenced this pull request Jan 22, 2020
* Added support for async importers

* Swagger importer v0.1 - supports import of workspace, environment and endpoints from swagger 2.0 specifications. Supports query params, headers and body. Mocks body of application/json endpoitns

* Refactor: added comments, removed function-in-function declarations

* Fixed import of yaml files. Added tests for both .json and .yaml
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
7 participants
You can’t perform that action at this time.