Skip to main content

Using JAX-RS inside NSF follow-up - Swagger UI

Today I returned from another great Engage conference. Going to conferences gives you some fresh ideas, energy from the peers and motivation for next work, but it also takes some energy due to travel. This time I also returned with a few tasks and having currently Friday afternoon I decided to start with an easy one, just publish something I had in my drawer for a while.

More than a year ago I blogged about the possibility of creating JAX-RS based REST services directly in NSF. I remember that  Per Henrik Lausten liked it at that time. He also immediately mentioned that Swagger UI would be nice too, but I was too busy then to follow up on this. In following months I needed it myself but I never published it. So, as promised to Per at Engage, here it is.

Swagger UI can be really nice to have for testing, but what's more important, you get OpenAPI specification, which you then can use to generate clients for your REST API. And all with close to no effort.

Here is how it looks ...

Here is a list of needed adjustments:

Upgraded libs and Swagger

To make it work, I had to update the Jackson libs and few supporting libraries. I'm not 100% sure if all are needed, but I normally just put there all libs that I get as Maven dependencies to be sure. Libs in the current version are from last August and I haven't tested this on Domino 10, so if you want to use it, you may want to check the latest versions and their compatibility.

Added OpenApiResource

Just added the resource to the existing wink_application file in my application.


Added some annotations

Just to show it works, I've added some extra annotations.

Added Swagger-UI to the app

I only copied the html version to WEB-INF folder. I also slightly modified the index.html file, so it finds openapi.json file generated in same nsf. Of course you can host it somewhere else and just point it to the url.

Adjusted the SwaggerConfiguration

This is probably the most tricky part. You need to have correct endpoint URLs generated in the openapi.json in order to work with the Try buttons. I think this can be also overridden in the UI, but it's always better to have it in the file directly, so also other tools work with that. I still don't consider this as the best solution as it's in the plugin, so server wide, but it gets the job done for now.

With all this in place, you can just happily keep adding JAX-RS annotated resources to your nsf and you'll get openapi.json/yaml files automatically. You can almost feel like working with some modern platform.

Get it here: (and yes, I've added additional todo to add some free license statement to the repo too, but for that, I also have to change the sample db to non-IBM one).

If you want to have similar features directly in the product, please vote for


Popular posts from this blog

Microsoft Word black box in numbering issue

This is awkward post, primarily to save the solution for future me. I have seen many people mentioning this problem over years and as I've struggled with it several times, I needed to find final and permanent solution. All editions of Microsoft Word from time to time suffer from bug in numbering. Instead of a number, black box is displayed. Sometimes it happens right after document is opened, sometimes during editing. Probably some internal structure of document gets corrupted, so based on level of corruption, different fixes could help. Many of them are listed at I took different approach. Since docx is just standard zip package with xml files, I decided to try if I can fix it manually. And it worked. When I extracted the docx, there was file called numbering.xml in word folder. When I examined that file, I found strange se

HCL Domino SSO with Microsoft Teams

 Microsoft Teams is probably one of the most used tools this year, it was already quite popular before the pandemic started to spread across the world this spring, but now most of the businesses I work with use it. After using it just like a chat/conferencing tool, many start to explore further capabilities of the platform. When working with Domino data in apps that are web-enabled, it can be quite easy - just add a web tab anywhere you want. The problem is, that you need to deal with user authentication. 

Using JAX-RS inside NSF

Last week Christian G├╝demann published new release of SmartNSF on OpenNTF  that contains cool new feature that Christian tweeted before. With new CUSTOM strategy it allows direct execution of Java code from REST API defined in router configuration. It's even better than it sounds as it initializes facesContext and XPages application if needed, so even access to beans works. I needed to start to build new REST APIs for few databases, so I decided to test new SmartNSF option and also other available options for REST APIs on Domino (there are several, check references at the end for more info). Since CUSTOM strategy requires dependency on SmatNSF in NSF project and also implementation of CustomRestHandler interface, it'd force me to do more changes in my code that I wanted to. If I need to change my code, why not adjust it for JAX-RS spec anyway. Existing Domino JAX-RS options had to packaged as plugins, which make it hard to call code that is currently in NSF. I could make i