Swagger for Domino Developers – Part Two: Swagger Editor

In Part One I gave a bit of background on Swagger. Now onto some tools. The Swagger Editor comes in an online version but you can also install it locally. My preference was previously to use the online version because the local install used NodeJS, so it was a bit outside my comfort zone. After IBM Connect, it was apparent NodeJS was something I should get exposure to, even though JavaScript development is not one of my preferences.

The first step, then, is to install NodeJS. NodeJS seems to be the JavaScript equivalent of Maven, a set of command line tools for pulling down dependencies and building something that can then be run. Eric McCormick covered it recently in his NotesIn9 episode as well. An upcoming NotesIn9 from me will also cover tools beyond Domino Designer. It’s not a case of “if”, but “when”. So why not now?

The instructions in the Swagger Editor documentation give a set of commands to run from the command line (presumably in a folder you want to create the Swagger Editor in).

The first command, “npm install -g http-server” uses NodeJS to install the http-server module globally (which means it can also be run from the command line, which we’ll be doing later). To get it to work, I had to switch folders in the command line prompt to a generic folder I use for temporary files.

I then hit a problem because I’m running on Windows, giving me this screen.

From what I found on StackOverflow, Windows doesn’t support the “wget” command to download files from the web. I tried the utility mentioned on that StackOverflow question, but I couldn’t get it to work. So I downloaded the zip file from the URL in the wget command, and manually extracted the files to my desired location.

Once I’d extracted the files, I navigated in the command line prompt to the folder where I unzipped them to and ran the final line of the commands, “http-server swagger-editor”. That launches the Swagger Editor using a lightweight HTTP server, like this:

The port can be configured by using the “-p” parameter (e.g. ” -p 8081″). The address can be changed with “-a”. And there are additional options like “–cors” in the documentation for the http-server NodeJS module. Now you have Swagger Editor running locally.

But what does this give you over using the online editor? We’ll see next time when I dig further into Swagger using Stephan Wissel’s IBM Connect demo, to see how it can be used to create a mock server, to store and retrieve JSON data with which to test the API.