Swagger for Domino Developers – Part One: Introduction

  |   Blog   |   2 Comments


At IBM Connect I led a team for the Hackathon. Technically and in terms of meaningful outcome, the day was a bit of a disaster. In terms of learning and working together, it was still enjoyable. My main focus for the day was never to win. For me, the main aims were for the team to learn something, whether from one another or from the tasks and to have a good time. After all, everyone was giving up a day of their time, and if it’s not enjoyable, everyone would be best served spending their time elsewhere.

The difficulty was around collaboratively building an application around Domino. Without a Domino server that everyone had access to, it was a challenge. We struggled to easily set up Bluemix with Cloudant as the back end, because of different levels of access from the team. The application was API-driven, with a Swagger API built early on. But the challenge we hit was the back end needed creating for data to be available, for the front end to be built. And until the application was built, integration with e.g IFTTT and Watson Workspace could not be built, although investigation work could be done. We tried to work with a mock data service, so the back end was not a factor, but this too was something that we struggled with. In hindsight, building an application from scratch had logistical challenges which we were unable to overcome.

However, with the knowledge I since gained and experience I’ve since gathered, building an API-driven application would have been much more achievable.


Swagger has grown in prominence over recent years to the extent that it is not just a set of tools about how to build and develop against a REST service efficiently and effectively, the specification itself has changed its name to become more generic, as the OpenAPI Specification.

Priot to Connect I had worked with it to some extent with ODA Starter Servlet, for which I created JSON that could be imported into the Swagger Editor. I had also become aware of Stephan Wissel’s GitHub project, a Domino Codegen for Swagger, to generate the server-side stub for Domino.

At Connect itself, Swagger gained greater emphasis again with confirmation that the new REST services would have OpenAPI specifications published (and this has already been started on OpenNTF’s GitHub). SmartNSF is also focussed on delivering OpenAPI specifications for the REST services it generates. And Stephan Wissel’s session Beyond Domino Designer talked more about Swagger tooling as well.

In a world of application integration, if you’re providing standard REST services in youor Domino applications for integration, publishing OpenAPI specifications for those REST services is best practice, will demonstrate Domino developers are embracing standards beyond the yellow bubble, and better document integration points for external developers integrating with Domino data. And providing better integration with Domino data helps stave off talk of migration and ill-informed arguments that “Domino can’t do that”.

Just to clarify a couple of points here. Firstly, like any other documentation framework, an OpenAPI specification can be good or bad. For example, showing your API takes a string or a number is useful only if you have details or examples that clarify what the string or number should be. Secondly, an OpenAPI specification only handles standard REST services. Anyone who attended my session at IBM Connect, which will be repeated at Engage in May, will know I am also a fan of GraphQL. GraphQL publishes its own schema and has a different documentation and testing method, as anyone who’s dug into Watson Workspace will be aware.

Where Next?

In the rest of this series I’ll cover setting up the Swagger editor, an overview of the Domino Swagger Codegen, and how to set up a mock server to develop against and persist data. If you’ve done a lot of development with Node.js, a lot of this will need little introduction. But if your work has been solely in Domino Designer or your focus has been Java and XPages, there is a lot that’s new and – in my case at least – left me stumbling around a bit at times and relying heavily on Stephan Wissel’s support. So it’s right to blog it, if only as future reference for myself and to help reinforce and clarify the notes I made at the time.

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.

  • Stephan H. Wissel | Mar 15, 2017 at 10:54 am

    Glad you like my little project. There is huge room for improvement there around view, form and code generation. Lots to be done

  • Paul Withers | Mar 15, 2017 at 11:25 am

    Jesse added some interesting functionality into ODA for generating the required DXL and writing to the ODP or, if I read it correctly, also the NSF. I think there’s a lot of potential for building a data NSF programmatically from various sources, including DXL generated from the codegen. That will also be covered in my round table at Engage, and I’ll blog about that too in due course, both before and (assuming I’m not the only one interested) afterwards.

Post A Comment