Documenting a Spring HATEOAS API [closed]

Question

Are there any plugins out there (similar to Swagger) which provide the ability to document HATEOAS APIs?

The Swagger interface is quite good but it doesn't have level 3 REST support.

Answer 1

I use spring-restdocs in combination with the HAL-browser.

You don't necessarily need HAL for restdocs though, although it is recommended.

Restdocs will generate code samples and link & field descriptors in the asciidoc format. You can then link to these asciidocs from inside the HAL-browser.

To see the result in action (although this is hardcoded), check this out: foxycart. Click on the little doc links next to the rels.

Answer 2

After further investigation I discovered HAL-browser (https://github.com/mikekelly/hal-browser) which is quite good. Although, your API must return content-type of HAL for it.

You don't need to configure anything on the server for this tool. Just open it in a browser and point to your API.