Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DS-3484 Spring REST documentation #1915

Open
wants to merge 17 commits into
base: master
from

Conversation

@tomdesair
Copy link
Contributor

tomdesair commented Jan 11, 2018

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
@tomdesair tomdesair force-pushed the atmire:DS-3484_Spring-REST-Docs branch from b4757d9 to 0e0ec5a Feb 8, 2018
Raf-atmire and others added 4 commits Feb 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.