Use API Umbrella for REST calls made through Swagger UI

[bajiat]

When making API calls in documentation browser, i.e. Swagger UI, it is desirable to use API Umbrella proxy, e.g. umbrella.apinf.io, for requests.

The API Umbrella proxy URL can be found in config.json (as api_umbrella.base_url)

One approach to this task would be to rewrite the .swagger file, changing the host property to match the api_umbrella.base_url.

Task

• Determine how to change .swagger file to use api_umbrella.base_url for the API Base URL
  • Specifically, the host in the .swagger file should be set to the same value as api_umbrella.base_url
• Test that API Calls through Swagger UI are being sent to API Umbrella

Reference

Check the Swagger specification for information about the host property.

Related

Related to #76.

Co-pilot: @elnzv

[bajiat]

@elnzv How about this one - would you be interested? This is a continuation of task #76, which is being implemented by @frenchbread. Please estimate the size if you can take it.

[55]

Will estimate the size after discussion with @frenchbread, since he was working on the related issue.

[brylie]

@frenchbread status report?

[frenchbread]

@brylie We kind of stuck with this one.

With @elnzv we found out that the only way to change the proxy to apiUmbrella is to download swagger.json file itself, change the host and base path values to be that we want and then use the same file for future requests in Swagger UI base url field.

[brylie]

Alright, that makes sense. Should we get together to plan this feature a bit? We can all three have a planning meeting later this sprint. @elnzv @frenchbread

[bajiat]

@elnzv @frenchbread @brylie I talked about this issue with @kyyberi as
well. If I understood correctly, he confirmed the approach @elnzv and
@frenchbread had figured out, i.e. changing the host in swagger.json.

2015-10-26 9:53 GMT+02:00 Brylie Christopher Oxley <notifications@github.com

:

Alright, that makes sense. Should we get together to plan this feature a
bit? We can all three have a planning meeting later this sprint. @elnzv
https://github.com/elnzv @frenchbread https://github.com/frenchbread

—
Reply to this email directly or view it on GitHub
https://github.com/apinf/api-umbrella-dashboard/issues/517#issuecomment-151052156
.

---

Taija Björklund
p. 040 5177 969
taija.bjorklund@gmail.com
www.linkedin.com/in/taijabjorklund

[frenchbread]

@brylie That's sound good. Let's set up a meeting then. @elnzv @bajiat

[kyyberi]

Yes, I had to manually edit a few files from swagger editor generated nodejs api skeleton to make it work correctly. Config was one and if I recall correctly, there was a variable in the beginning that was never used.

[frenchbread]

PR #590 created.

The approach is

1. Read the text file when selected.
2. Convert text data to JSON object to be able to refer to its values by key.
3. Modify values of host and basePath to what we need.
4. Convert object back to JSON string.
5. Construct new File( ) using updated file data. (This is implemented in two steps: First constructing new Blob( ). Second: new File( ) that takes Blob as parameter)
6. Saving file in Mongodb collection

Issues

• Currently custom values of basePath and host are hardcoded. Since all the above process is happening on a client-side, there is no way to access Meteor.settings data.

Testing

1. Create new apiBackend. While this process, upload new documentation file e.g swagger.json. (For example default one: http://petstore.swagger.io/v2/swagger.json)
2. Go to documentation viewer page.
3. In drop down manu select uploaded file.
4. iFrame will give an error since the remote swagger UI was not able to access local file.
5. The path to documentation file is provided in there.
6. Copy this path to a new tab to see updated host and basePath values.

[brylie]

Make sure to store the original values for basePath and host, so they can be retrieved later. I.e. keep the file integrity and override the values on a temporary basis where needed.

[brylie]

Also, the Swagger UI is retrieved from our server. What 'remote swagger UI' are you referring to?

[brylie]

According to the Swagger UI docs, we can simply pass in a JSON string when invoking the Swagger UI. This is probably a better approach than using an iframe.

[brylie]

Example code for invoking Swagger UI in our template:

Template.documentationBrowser.rendered = function () {
  var swaggerUi = new SwaggerUi({
    url:"http://petstore.swagger.io/v2/swagger.json",
    dom_id:"swagger-ui-container"
  });
};

swaggerUi.load();

It may be possible to pass a JavaScript object directly in to the URL parameter, or at least write a route that returns the JSON fields stored in a collection.

[frenchbread]

@brylie "remote swagger UI" because it loads its data through iFrame

[brylie]

OK, see above comment.

[frenchbread]

Created meteor-package for SwaggerUI.

@brylie I am getting an issue in browser console Uncaught ReferenceError: require is not defined. How this can be solved on a client side? For swaggerUI source I used https://github.com/swagger-api/swagger-js

[brylie]

OK, your package should include only what is in the /dist/.. folder.

[brylie]

Also, be sure not to 'provide' or 'export' the HTML files when defining your package. The HTML files will cause conflicts. All you need to export are the JS, CSS, fonts, etc.

[brylie]

@frenchbread and I added comments to a Meteor packaging feature request on Swagger UI project.

[frenchbread]

Please review #590.

Tested that requests are sent to API Umbrella:

Also issue #649 partly implemented here. Since we moved from "FS collection" to "pure mongo document" approach, currently swagger document Title is shown in the select box: