-
Notifications
You must be signed in to change notification settings - Fork 1.3k
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
Closed
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tomdesair
added
work in progress
PR is still being worked on & is not currently ready for review
interface: REST API v7+
REST API for v7 and later (dspace-server-webapp module)
labels
Jan 11, 2018
…ream and bitstreamformats
…e the REST API documentation
tomdesair
force-pushed
the
DS-3484_Spring-REST-Docs
branch
from
February 8, 2018 15:36
b4757d9
to
0e0ec5a
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Labels
interface: REST API v7+
REST API for v7 and later (dspace-server-webapp module)
work in progress
PR is still being worked on & is not currently ready for review
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
TODO
There are still some things we would like to improve if we decide to continue with this documentation framework: