Blog

Swagger for Domino Developers – Part Two: Swagger Editor

  |   Blog   |   2 Comments

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.

AUTHOR - Paul Withers

Paul Withers has been an IBM Champion since 2011, has been an OpenNTF Board Member since 2013, has worked with XPages since 2009, co-authored XPages Extension Library and was technical editor for Mastering XPages 2nd Edition. He is one of the developers on OpenNTF Domino API as well as contributor to a variety of other OpenNTF projects.

2 Comments
  • Frank van der Linden | Apr 5, 2017 at 2:06 pm

    when you are on compatible Docker system, like macOS, Linux or Windows 10, you can easily use swagger editor in a docker image. Easy to use and easy to share with others

  • Oliver Busse | Apr 6, 2017 at 4:20 pm

    wget and other commands are available after you install CMDER, a great CLI replacement on Windows.
    It also contains a full GIT client if you haven’t one installed anyway.
    I use it every day: http://cmder.net

Post A Comment