Defining an API using swaggerhub

Having previously developed API specifications using little more than a Markdown editor i was interested to see what benefits i would get from using a tool to generate an API. Having been introduced to swaggerhub here’s a guide on how to set it up for a JS project and my initial thoughts on using it.

😀 Pros

  • Auto generated docs
  • An endpoint that will produce the fields with static example data
  • Versioning, diffing
  • An auto generated JS project that provides an API for you to call without having to write an XHR (uses superagent under the hood)

😩 Cons

  • It’s a tool, so there’s a learning curve
  • There’s a kitchen sink of fields and relational model between requests and payloads. You might not need all of them, but you have to adhere to them
  • Clunky UI in SwaggerHub — lots of menus and icons that aren’t clear
  • Auto generated code is like most auto generated code. Abstract and covers all edge-cases your setup may not have. Also definitely not made for readability
  • If you use the API, it will be your comms layer, maybe you want more control over this
  • Anything more than static data from the test endpoint will require you pay for, and learn another tool (Smart Bear VirtServer — €1,067 per year)
  • swaggerhub is not free - $888 for a premium account per year

Process

This was my process for creating a very simple API, setting up a mock endpoint and getting a client in JS that can talk to that endpoint. My app is to the world’s simplest investment app, with a /userdetails call and /account that shows the account balance.

Create API

Signup at swaggerhub https://swaggerhub.com/. Logging in with github was a nice integration

Create an API — i used “Simple API”

You then get taken to an editor to create the API. At this point i ended up stripping out many things like tags, summaries, parameters. Here is my API .

Create a fake endpoint

Once complete add the “API auto mocking” extension. This produces a URL that gives test output, the values are the example ones given in the spec.

Mine was at https://virtserver.swaggerhub.com/fauna5/investment/1.0.0/user and returned this JSON

Auto generated client

swaggerhub will create you a library that connects to the endpoint using HTTP and exposes an API at the User and Account object level. This reduces the code you need to write to get your app started. For JS it comes in an NPM project that you can publish and then consume in your app.

Download > Client > javascript

Once downloaded, unzip, run

npm install
npm t

and run the tests.

You then have options to upload this to github or publish to a NPM repo. The aim is that this package is consumed by your App.

Github sync

Alternatively you can get swaggerhub to send the auto generated code to github. This will create a branch in an existing project and push the code there. Mine got pushed to https://github.com/fauna5/simple-investment-api/tree/SWAGGERHUB

Add integration > GitHub sync

Call the API

The app now just needs to do

var InvestmentApplicationApi = require(‘investment_application_api’);
var api = new InvestmentApplicationApi.DefaultApi()
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log(‘API called successfully. Returned data: ‘ + data);
}
};
api.accountOverview(callback);

Thoughts and Tips

  • I made a few mistakes when creating the initial API in the editor. The syntax validation kicked in, but it was a little painful to find out where my error was. Some in-line highlighting could be useful here
  • The generated code has a LOT of UMD boilerplate in it. Makes it run most environments but makes the code ugly
  • The tests for the generated code only test the objects defined and not the actual endpoints. Those are commented out by default. You have to implement them if you want them
describe(‘userDetails’, function() {
it(‘should call userDetails successfully’, function(done) {
//uncomment below and update the code to test userDetails
//instance.userDetails(pet, function(error) {
// if (error) throw error;
//expect().to.be();
//});
done();
});
  • The UI is so clunky, sometimes there are fields that are not explained e.g. “Update host setting” in auto mocking config. Some inline help could be better here. None of the icons have tooltips. Some buttons appear on the screen that are enabled but don’t do anything. Some labels are also truncated so you can’t read them. It just makes a complicated thing even harder to work with.
  • The help is pretty good with some helpful tutorials

Conclusions

swaggerhub is a great idea and I can see the power of this tool. Allowing people to contribute on a living document that produces versioned APIs.

The auto mocking and auto generated code are nice touches, however it seems a bit complicated to get set up. On balance i think i might just write my own mocks. Being able to control the mock logic in code will outweigh the slower setup time in a long-running project.