Including HAL-browser in Spring Boot without using Spring Data REST
In our current project we are building up a cloud service. Therefore we wanted to include the HAL-browser to make our hypermedia-based API easily discoverable (also for non-technicians). But we don't want to use Spring Data REST. In this short post we will show you how you can do this.
First of all, if you are using Spring Data REST to expose your repository through an API, including and using the HAL-browser is a very simple step. The only thing you have to do is to add the following dependency to your Gradle build file.
After that you can reach the HAL-browser at http://<host>:<port>/browser/index.html and traverse the API. Moreover, if you are using CURIEs the HAL-browser also includes easily accessible links to your documentation and integrates it within the browser.
But the spring-data-rest-hal-browser is not only a simple wrapper of the original HAL-browser. It requires some more dependencies including Spring Data REST Webmvc and as soon as this library is on your classpath it performs some “magic” or autoconfiguration. For example it exposes some application/alps+json metadata (profile) endpoint and far worse than that it exposes all endpoints defined in your Spring repositories, even the DELETE method is suddenly available for your endpoint. Of course this behavior can be disabled by adding the main Spring Data Rest project as a dependency and configuring the repository to be not exported (like shown in the code below – reference). But overall it seems not reasonable to invest that amount of effort just because of the handy HAL-browser. And in some cases you don’t even need or want a new dependency like Spring Data Rest and to take all these additional steps.
We want to introduce two alternatives how to include onlyx the HAL-browser without any additional dependency and a minimum of configuration:
One way is to add a special resource handler
The other one is to include it by adding a Gradle task
For that we use the HAL-browser package provided by Webjars. A Webjar is a client-side web framework or library that is packaged into a JAR file. Therefore the packaged library can easily be integrated into a Java application with the help of your favorite dependency management tool.
So everything we have to do is to add the correct Webjar to our Gradle dependencies block in our case. After that you can choose between the two described alternatives.
Option 1: Webjar + Resource handler
First we want to show you how to serve the browser with Spring by adding a special resource handler to your configuration (for more details see here):
The second option is to add a Gradle task that basically extracts the needed files from the webjar, strips the version information from folder structure and copies them into the “static/” folder of your JAR. This is then served by Spring automatically, without any additional configuration.
For that we added a configuration “halbrowser” and the “halbrowser” task to our build file and configured the “jar” and “bootRun” steps to depend on this task.