Including HAL-browser in Spring Boot without using Spring Data REST

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:

1. One way is to add a special resource handler
2. 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):

This will serve the HAL-browser at http://<host>:<port>/browser/browser.html.

Option 2: Webjar Gradle task

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.

After you run the resulting JAR from the Gradle build or start it with bootRun, the HAL-browser will also be served at http://<host>:<port>/browser/browser.html. If not, check if your Spring app serves static content which is the default configuration in a Spring Boot application, but you can also configure it by yourself, see Configuring Serving of Resources.

We prefer the Gradle task because it doesn’t even force us to change one line of our application code. But both solutions are valid and have the same effect in the end.

If you have any questions or want to give some suggestions just leave a comment.