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.

io.swagger.v3.jaxrs2.integration.resources.OpenApiResource

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: https://bitbucket.org/pradnik/pristo_rest/src/master/ (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 https://domino.ideas.aha.io/ideas/DDXP-I-409

Comments

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 https://answers.microsoft.com/en-us/office/forum/office_2010-word/ms-word-header-styles-are-showing-black-boxes/c427b21c-dcda-46ce-a506-b9a16c9f2f3f


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 section in h…

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 it wor…

WSL, HCL Volt and some Docker

My list of new technologies to try was growing fast in past months, but now I finally can try to catch up with all the cool improvements that can be used to enhance my/your dev experience.
Microsoft has enhanced the Windows Subsystem for Linux this year and Docker completely changed the way Docker Desktop for Windows is integrated into the operating system. The most important change for me was that I can finally run Docker Desktop and VMWare Workstation on my machine in parallel. When I was looking for some good use cases to try how it works, HCL Domino was a logical choice. HCL started to even publish official Docker images for every release and some pre-releases are only available as Docker images. I have many test Domino machines running in VMs, but I had no HCL Volt. If you don't know that HCL Volt is - it's a new low-code platform that brings HCL Form Builder experience, now know as HCL Leap, to HCL Domino, which then serves as a data store and application server. When I…