hal-explorer

hal-explorer copied to clipboard

:doctype: book

image:https://github.com/toedter/hal-explorer/workflows/Build/badge.svg["build", link="https://github.com/toedter/hal-explorer/actions"] image:https://codecov.io/gh/toedter/hal-explorer/branch/master/graph/badge.svg["coverage", link="https://codecov.io/gh/toedter/hal-explorer"] image:https://img.shields.io/maven-central/v/org.webjars/hal-explorer?color=green["maven-central", link="https://search.maven.org/artifact/org.webjars/hal-explorer"] image:https://img.shields.io/badge/license-MIT-blue.svg["MIT", link="http://toedter.mit-license.org"]

= HAL Explorer

With HAL Explorer you can browse and explore http://stateless.co/hal_specification.html[HAL] and https://rwcbook.github.io/hal-forms/[HAL-FORMS] based RESTful Hypermedia APIs. HAL Explorer was inspired by Mike Kelly's https://github.com/mikekelly/hal-browser[HAL-Browser]. HAL Explorer also supports Spring Profiles.

== Documentation, Demos & Cloud Deployment

Here you find the documentation for the latest release and the current snapshot, as well as a demo (with examples) of the latest release and the current snapshot: |=== | Release | 1.2.1 | https://toedter.github.io/hal-explorer/release/reference-doc/[Reference Documentation] | https://toedter.github.io/hal-explorer/release/hal-explorer/#theme=Cosmo&uri=examples/examples.hal-forms.json[HAL Explorer Demo] | Snapshot | 1.2.2-SNAPSHOT | https://toedter.github.io/hal-explorer/snapshot/reference-doc/[Reference Documentation] | https://toedter.github.io/hal-explorer/snapshot/hal-explorer/#theme=Cosmo&uri=examples/examples.hal-forms.json[HAL Explorer Demo] |===

You also find current release at https://hal-explorer.com.

== TL;DR

image::./doc/img/hal-explorer.png[HAL Explorer]

== Features

• Responsive design
• Syntax highlighted response body
• Custom request headers
• Available Themes ** Bootstrap 5 default theme ** https://bootswatch.com/[Bootswatch themes] ** https://github.com/vinorodrigues/bootstrap-dark-5[Dark theme]
• 2 layouts ** 2 columns layout with optional documentation ** 3 columns layout with documentation always visible if available
• API URL, theme, layout, and request headers stored as URL fragment
• Support for Spring Data Rest profiles to populate properties in request editor
• Support for HAL-FORMS templates ** Template elements in response explorer (see screenshot) ** Template properties in request editor ** Options support in request editor
• HAL-FORMS property constraint validation in request editor

== Demos with Spring based Backends

You can also play with the latest snapshot version of HAL Explorer in demos that provide backends implemented with Spring. I host these demos at Heroku, so please give them a bit of time to warm up (this might take up to 1 minute).

• For HAL: https://chatty42.herokuapp.com/hal-explorer/index.html#theme=Cosmo&url=https://chatty42.herokuapp.com/api[Chatty API] (Spring Data REST Backend)
• For HAL-FORMS: http://hypermedia-movies-demo.herokuapp.com/hal-explorer/index.html#theme=Cosmo&uri=http://hypermedia-movies-demo.herokuapp.com/api/movies/1[Movies API] (Spring HATEOAS Backend)

== Development Server

Run yarn start for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files. The development server has a build-in proxy configuration so that all calls to /api are forwarded to localhost:8080/api. This is convenient when you want to test a local server without having to deal with CORS. If you run yarn startl, an additional file server is started with port 3000. In the test-data directory, you find some JSON examples. Try it out with the URL http://localhost:4200/#uri=http://localhost:3000/movies.hal-forms.json.

== Build

Run yarn build to build the project in production mode. The build artifacts will be stored in the dist/ directory.

== Gradle/Java Build Support

If you have Java installed, you can also build the project with Gradle. The Gradle build will install Node.js locally in the project directory. Run ./gradlew build to build the project in production mode. The build artifacts will be stored in the dist/ directory.

== Integration in your Backends

If you want to use a released version of HAL Explorer in a Java-based project, you could define a dependency to the HAL Explorer WebJar.

Maven: [source,xml] <groupId>org.webjars</groupId> <artifactId>hal-explorer</artifactId> 1.2.1

Gradle: [source, Groovy] implementation 'org.webjars:hal-explorer:1.2.1'

When you use the WebJar with Spring Boot, you can access the HAL Explorer at /webjars/hal-explorer/1.2.1/index.html. The easiest way to integrate the upstream version of HAL Explorer into your backend would be to clone this Git repo, do a production build and then copy the content of the dist folder to a location accessible by your backend server. When you use Spring Boot, a good location in your project's source tree would be src/main/java/resources/static/hal-explorer.

== Running Tests

• yarn test to run the unit test suite against your default browser.
• yarn test-headless to run the unit test suite against headless Chrome.
• yarn e2e to run the e2e test suite against your default browser.
• yarn e2e-headless to run the e2e test suite against headless Chrome.

Take a look at package.json for more test options.

[[license]] == License

MIT, see http://toedter.mit-license.org