Swagger for Domino Developers – Part Four: Generating Domino Design Elements

  |   Blog   |   1 Comment

This final part has taken a while, because of problems that will become apparent during the blog post! But I’ve finally overcome them, in a (hopefully) future-proofed manner, which I’ll also go into.


Another one of Stephan Wissel’s projects on GitHub is the Swagger Domino Code Generator. If you’ve followed the other parts of this blog series and looked at the Swagger Editor, you’ll see there are various code generators for generating server-side code:

But Domino is not one of them. This is what Stephan’s project provides.

First of all, it doesn’t add anything into that Swagger Editor menu. It’s a command line utility, run as a jar file, and the jar file needs generating from the source code using Maven. But the good news is it’s straightforward to do those steps.


First you’ll need to download and install Maven. A key requirement you’ll need is a Java version higher than Java 1.6 (see the install link on the Maven website). I’d recommend downloading the latest version of Java JDK from the Oracle website (Google “Java JDK” and it will be the first link), and running the installer. Just choose where you want to install to and click through the installer. Then extract the Maven zip file to a location of your choice and set the environment variables for JAVA_HOME and add the Maven bin folder to the PATH environment variable. For info, I set JAVA_HOME as a (Windows) user environment variable and added the Maven bin folder to the system environment variable PATH. If you start a new command prompt, and type mvn -v you should then get the relevant Maven version and Java version used echoed back to you. (Following on from the tip Oliver Busse gave on an earlier blog post, I’ve started using Cmder for that.

Once Maven is fully installed, you could download the CodeGen project from Stephan Wissel’s GitHub and extract it. However, the underlying  Swagger version has changed, and it references a snapshot that’s no longer available. So it fails to build. Changing just the version numbers doesn’t work either, because the tests fail to run during the Maven build. And the output of the tests is critical for the final part of the build, so using the Maven switch -dSkipTests doesn’t help.


The solution was to download a version of Swagger from GitHub and manually apply the changes. This may sound tricky, but the commit history on Stephan’s GitHub repo made it easy to work out what needed to be done.

The following files / folders needed copying in:

  • bin/
  • modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/
  • Everything in modules/swagger-codegen/src/main/resources/ibm-domino-server/
  • Everything in samples/server/domino/

In addition, a line needed adding to modules/swagger-codegen/src/main/resources/META-INF/services/io.swagger.codegen.CodegenConfig, to tell it that the new module “DominoServerCodegen” was available:


I’ve already done all that on my GitHub, against the master branch of swagger-codegen, so hopefully it will continue working. Either download it from there or, if you have Git installed on your PC, you can alternatively use a command prompt and navigate to wherever you want to install it, and issue the command git clone -b feature/domino-server

Once you have it downloaded, build it from a command line prompt by navigating to the folder you’ve extracted or downloaded it to, then issuing the command mvn install. This will generate the jar file needed for the generating Domino server design elements.


Now you’ll need a yaml file (like “foodstore.yaml” from the Mock Server from the last part) and a folder to output to. For ease in the command line code, I put the yaml file in the folder above the git repository and added a folder called “swagger-output-domino” alongside it.

Then in your favourite command line tool, navigate to the folder containing the yaml file and run the following command:

java -jar swagger-codegen/modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -l ibm-domino-server -i foodstore.yaml -o swagger-output-domino/

There are some key variables you may need to change here:

  • The first filepath (after -jar) points to the swagger codegen jar, relative to the current location. If you’ve just followed this tutorial to the letter, you won’t need to change this.
  • The second filepath (after -i) points to the yaml file as input for the command line tool.
  • The third filepath (after -o) points to the folder to output the content.

Once it runs, in your output folder, you’ll find very basic DXL forms and views for the objects in the Swagger definition. These are in the src/formview folder. The Forms have all the relevant fields defined in the yaml file, and the Views have all columns defined in the yaml file, all columns resortable, and a selection formula restricted to the relevant Form. These may not be absolutely what you need, but it’s a useful starting point for a DXL import into your NSF.

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 | Jun 26, 2017 at 5:15 am

    Thank you for covering that little project. It could use a little TLC like generating a CRUD XPages app. Or a REST plugin for Domino OSGi
    In any case: the swagger maintainers would accept pull requests when it gets more mature. Then it will become part of that menu

Post A Comment