DS-3484 Spring REST documentation

[tomdesair]

Introduction

@Raf-atmire and I have been working on a proof-of-concept that integrates Spring REST docs with the new DSpace 7 REST API. Spring REST docs allows us to document the REST API endpoints by writing (special) tests for those endpoints. Those tests result in ASCII doc snippets which can then be used to write the documentation. More information on the ASCII doc format can be found here.

These ASCII doc files are transformed to HTML so that they can be hosted within the REST webapp. The current URL is <rest-endpoint>/documentation/index.html.

In addition, we configured Spring HATEOAS to generate CURIEs on each endpoint to the corresponding documentation page. More information on CURIEs can be found in the CURIEs section of this page. Note that in order to be able to use CURIEs, we had to change the rel names.

These CURIEs are picked up by the HAL browser. For each link or embedded resource with a CURIE, the HAL Browser will also display a link to the documentation under a booklet. When clicking the booklet, the documentation will open in the right results pane (see screenshot).

As mentioned above, the documentation is generated by executing tests. In order to be able to skip the "regular" tests and to only execute the documentation related tests, we added an additional maven profile only-rest-documentation.

Testing

You should build this PR using: mvn clean package -Dmaven.test.skip=false -P only-rest-documentation. That way, only the documentation related tests are executed in order to generated the required ASCII doc files.

The following rels have documentation written by @Raf-atmire:

• items (list + singular item)
• owningCollection (single collection)
• templateItemOf (single collection)
• bitstreams (list + singular bitstream)
• bitstreamformats (list)
• content (very minimal, no real content yet, just the basic headers and curl command)

TODO

There are still some things we would like to improve if we decide to continue with this documentation framework:

• Change the documentation path to include the REST category instead of the curie
• Update to the latest version of Spring Rest docs
• Rebase on master
• Improve the index documentation document
• Document more endpoints