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 SwaggerTo 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.
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.
If you want to have similar features directly in the product, please vote for https://domino.ideas.aha.io/ideas/DDXP-I-409