Swagger for Domino Developers – Part Three: Mock Server and Thanks Stephan Wissel
Stephan Wissel – One of Our “IBM” Champions
As you may have seen, Stephan Wissel has recently left IBM to join SalesForce, as Rene Winkelmeyer and Mikkel Heisterberg did last year. because this part of my blog series will cover Stephan’s session from IBM Connect earlier this year and setting up a mock server for an OpenAPI (aka Swagger) definition, it seems a good time to thank him for his efforts over the years. His twitter feed has been very helpful in giving early notice of any new XPages StackOverflow questions. He has regularly pushed the boundaries of IBM tooling and I will forever associate the acronym “YMMV” with his blog posts. His blog posts on using vert.x with Domino (primarily driven by work on Verse on Premises) are definitely on my radar for getting some experience with in the coming months. And his branch of Verse on Premises where he was integrating ODA into the project has been useful for driving forward the development of the MessageQueue functionality added to ODA recently, if for nothing else. But his help recently was invaluable for getting the Swagger mock server up-and-running and understanding how it’s working alongside the Swagger editor. There is a big opportunity for IBMers to fill the gap he has left and I would encourage developers in IBM to take that opportunity and not let the evangelism and enablement Stephan was famous for become a fading memory.
Setting Up The Mock Server
The mock server is in the mockserver folder of Stephan’s project for his IBM Connect session. This is a NodeJS application that uses swagger-express-middleware, which can parse an OpenAPI specification and provide fully-functional mock implementations, including data persistence. This means you can use the POST endpoints to store data and retrieve it via the GET methods. This means that if front-end and back-end development are being split, the OpenAPI specification can provide a contract allowing the front-end developers to build and test against the specification without a database but instead using persistence in a JSON text file, and the back-end developers to build and test the database persistence with something like Postman. During the IBM Connect hackathon, this would have been extremely useful!
Once the source code has been downloaded, because it’s using NodeJS for dependency and build management, you will need to use a command line interface (thanks to Oliver Busse’s comment on my last blog post, I’d suggest cmder). Navigate to the “mockserver” folder and issue the command
npm install. This will load all the dependencies. Then to start the mock server, issue the command
node app.js. This runs the app.js file that’s in that folder. There are two noteworthy points in that file. The reference to “../frontend/foodstore.yaml” loads the foodstore OpenAPI specification from the frontend folder at the same level as the mockserver folder. The
app.listen() function tells it to listen on post 8000 and of course that can be modified.
The foodstore.yaml file is also important here, and you’ll need to make a modification. It has a “host” JSON property, and this needs to match what you’ve told the mockserver to listen on (by default “http://localhost:8000”). The “basePath” property is then the subfolder of the mockserver where it should store and retrieve the data. The file it will look to is defined in the “paths” property, “/food”.
Don’t make the mistake I did of trying to navigate to http://localhost:8000 – there’s nothing there. Instead it’s looking to http://localhost:8081/api/food. You can now run the POST methods to put data into that file or GET methods to retrieve any data in there.
In the next part we’ll cover another of Stephan’s projects, for generating Domino code from an OpenAPI specification.