Swagger HAL Navigator

Swagger HAL Navigator is a Spring Boot starter that adds a standalone Swagger UI page for HAL APIs. It renders buttons next to HAL _links and Location response headers, then opens the matching documented operation with URL parameters prefilled.

Quick start

This project is currently used locally as a 1.0.0-SNAPSHOT dependency. Build and install all of its Maven artifacts (the parent POM and all modules) into your local Maven repository (~/.m2/repository) before adding the starter to another application:

mvn clean install

The target Spring Boot application must already expose a working Swagger UI, including its browser assets, and an OpenAPI document. This starter does not provide Swagger UI or generate OpenAPI documentation.

Then add the starter to the target application's dependencies:

<dependency>
    <groupId>pl.mpietrewicz.swagger</groupId>
    <artifactId>swagger-hal-navigator-spring-boot-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

By default, the application must make Swagger UI assets available at /swagger-ui and the OpenAPI document at /v3/api-docs. If it uses other paths, configure them as described below.

After starting the application, open:

http://localhost:<port>/swagger-hal-navigator

How it works

The navigator adds navigation controls to HAL _links and Location response headers. Selecting one opens the corresponding Swagger UI operation and fills its parameters from the link URL.

It matches the link URL to an OpenAPI endpoint path, then resolves the operation primarily by matching the HAL relation to its operationId. Identifier formatting differences, such as apply-promotion and applyPromotion, are handled automatically. For the most reliable navigation, use the same value for each actionable HAL relation and its OpenAPI operationId.

Configuration

swagger:
  hal-navigator:
    openapi-url: /v3/api-docs
    swagger-ui-assets-path: /swagger-ui
    debug-enabled: false

• openapi-url points to the OpenAPI document used by Swagger UI.
• swagger-ui-assets-path is the application path where the existing Swagger UI frontend assets are served.
• debug-enabled enables the navigator's browser-console diagnostics. Add ?halNavigatorDebug=true to the navigator page URL for a one-off debugging override.

The application must already provide Swagger UI, including its browser assets, and OpenAPI operations should have stable operationId values. For Springdoc, declare them with @Operation(operationId = "..."); actionable HAL relations should use the same value.

Security

The starter does not modify application security. If static resources or API documentation are protected, allow the following paths according to the application's security model:

/swagger-hal-navigator
/swagger-hal-navigator/**
/swagger-ui/**
/v3/api-docs/**

Only the first two paths are provided by this project; adapt the Swagger UI and OpenAPI paths to the application's configuration.

Limitations

• The navigator supports HAL _links; it does not support JSON:API links, Siren, or HTTP Link headers.
• HAL URI templates such as {?page,size} are not expanded.
• Link matching requires a corresponding OpenAPI path and works best when rel matches operationId.
• An external link origin is not followed. Its path can be matched only against the OpenAPI document loaded by the current Swagger page.
• The form-filling integration relies on Swagger UI DOM selectors and controlled-input behavior. A Swagger UI upgrade may require updates to the navigator.

Troubleshooting

• If the page shows module or stylesheet errors, verify that /swagger-hal-navigator/** is publicly served and that the browser can load JavaScript modules.
• If an arrow button is disabled, confirm that the HAL link has a valid href, its path exists in the configured OpenAPI document, and the relation matches an operationId or an available fallback rule.
• If navigation opens an operation without values, verify that the link path and query parameter names match the OpenAPI parameter names.
• If HAL links are not displayed or do not match the expected Swagger operations, enable debug logging. The browser console then shows link-matching diagnostics, navigation actions, form-filling attempts, and warnings.

License

Copyright © 2026 Marek Pietrewicz.

Licensed under the Apache License, Version 2.0. See LICENSE.