Bundle Admin API Swagger file with API Umbrella?

[brylie]

User story

As a developer I need an API Umbrella instance to provide a self-referencing Swagger file so that I can easily create a JavaScript wrapper around the Admin API

As a system administrator I would like for an API Umbrella instance to provide a self-referencing Swagger file so that I can make test calls to our API Umbrella instance from the Swagger UI

Goal

The goal of this feature request is to have API Umbrella provide a self-referencing Swagger documentation file, for any given API Umbrella instance.

Feature

We are interested in using swagger.js to integrate with one or more API Umbrella instances:

var Swagger = require('swagger-client');

var client = new Swagger({
  url: 'http://umbrella.example.com/api/v1/swagger.json',
  success: function() {
    client.api.get(...);
  }
});

The only swagger descriptor file I can find is located at api-umbrella.readthedocs.org.

Background

We have been maintaining an API Umbrella integration package for Meteor.js. The package uses the API Umbrella Admin API to manage a given API Umbrella instance. Maintaining this package seems unnecessary, when the swagger.js would serve the same purpose.

Considerations

Rails

Currently, API Umbrella Admin API is provided by the Ruby on Rails based API Umbrella Web. Initially, the self-documented Swagger file might be provided by the Rails frontend.

• API Controller
• API Models
• API Helpers

  Lua

In the future, it may prove beneficial to consolidate the platform by moving the Admin API into the Lua port, which currently contains a minimal HTTP API.

[diegojonio]

I couldn't find one on a running instance either. The Admin Api documentation is on this web-site: https://api-umbrella.readthedocs.org/en/latest/admin/api.html

But I found a Meteor wrapper for the Admin Api, check it out: https://github.com/apinf/meteor-api-umbrella

[brylie]

Jep, we are hoping to deprecate that module if API Umbrella can include a self referencing swagger.json. E.g. the API document would refer to the base URL of the API Umbrella instance.

[diegojonio]

Would it be embedded on the api-umbrella-static-website?

[brylie]

Basically, yes. Although the baseUrl would need to be dynamically set by the server, so that the API is self documenting.

[brylie]

@GUI, we are still waiting on your input here. We can provide some development time towards this feature request.

[shaliko]

The task can be managed by adding "swagger-blocks" or "ruby-swagger".

[brylie]

@shaliko would either, or both, of those modules work well with the current API Umbrella Web structure?

[shaliko]

@brylie Based on Readme of these GEM's, both can manage the goal of this issue. I don't see any difference related to API Umbrella Web structure.

[brylie]

OK, I have created an issue in our project repository, so that we can track the progress towards this goal. We will try to work with @GUI, so that our efforts are compatible with the goals of API Umbrella.