Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
DS-3484 Spring REST documentation #1915
@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
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
You should build this PR using:
The following rels have documentation written by @Raf-atmire:
There are still some things we would like to improve if we decide to continue with this documentation framework: