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

Labels:

Comments

Post a Comment

Popular posts from this blog

XPages Date Field Issue: Solving the One-Day Jump on Every Save

 A user reported a very strange issue - when a document with a date field is saved, it changes the value one day to the past. With every save. But only for some dates, not all. It turned out to be a mystery that goes deep into XPages and Notes/Java APIs. I've posted a sample on OpenNTF Discord and Serdar tried it on his server - no issue. But he uses the GMT zone and I have CET (Windows set to UTC+1 - Amsterdam, Berlin... to be precise). To cut it short, the issue is caused by daylight saving interpretation between Notes and Java. The date fields (because XPages have no notion of real date-only fields) are stored with 00:00 time component and for some dates the conversion back to Java Date resulted in 23:00 on the previous day. XPages that get the date component as String for the input field, which is then saved back as a previous day during document save. The app is full of date fields and I couldn't add custom logic to every save operation, so I tried to fix it at XPages conv...
Post a Comment
Read more

HCL Domino 12.0.2, Engage 2022 and HCL Factory tour Milan

 I haven't published my recap after Engage this year and the recent HCL Factory tour in Milan is a great opportunity to write a summary about what's happening in HCL (mostly Domino) space. It's a mix of news about 12.0.2, future directions, and my impressions, so it can be a bit chaotic, but I got the impression that many people see it similarly.  Engage 2022 Engage 2022 was great (as always). I love the atmosphere in Brudges. I visited it once after Engage a few years ago and I was happy to come back. This was also the first time I had the opportunity to speak at Engage, which obviously made it a bit more stressful, but also more fun. Together with Domino Jams, HCL continued conversations with customers and partners about the future of their products at Engage. Many of these ideas were now discussed in greater detail in Milan, some of them were even demoed.  My main takeaways from Engage were: Nomad (web and mobile) are a great addition to Notes family Restyle is a great...
Post a Comment
Read more

XPages EL/class-loader memory leak (now with solution)

 We have recently experienced OutOfMemory crashes of XPages app server. The server was recently upgraded to 12.0.1FP1, but we were getting some panic crashes in HTTP even before the upgrade (it was 9.0.1FP10). Our hopes were that the upgrade would stabilize the server, but it's not the case. At least now I start to see what's the problem.  update 8.12.2022 There were actually 3 different leaks. I have rewritten the article to be a bit more clear. I also re-run some of the tests on 9.0.1FP10, so I assume the problems are also in earlier versions. Problem 1 The server is hosting over 1000 NSF sharing the same design + some other custom apps. Not all NSFs are used via web as the app still has classic Notes UI in parallel, so it's a bit tricky to estimate the load. By using tell http xsp show modules I usually see around 350 NSFs active. We kept the default application timeout that should provide reasonable application recycling if it's not used continuously.  We started to...
Post a Comment
Read more