Get rid of compile/test dependency in documentation page rendering
Problem to solve
- The documentation is not easily accessed because the artefacts do not have a domain/subdomain to be uploaded and afterwards consulted, we used to have the: https://docs.mlreef.com/master URL. But since the branch was removed we now cannot find the documentation.
One reason for this is, that our technical API documentation is rendered by Spring Rest Docs and then copied to the Gitlab Pages job. This interdependency has disadvantages in the job layout and sometimes fails because the code is currently not stable.
- Many sections of the document are broken. The most common error is
Snippet not found for
.
Fix up the broken sections so that FE devs can consult and understand how to interact with the APIs without asking the BE devs or reading the BE code:
The API endpoints which need revisiting are mentioned below.
Proposal for Technical Solution
The solution for this will be a two-headed approach:
-
After Spring Rest Docs generates the Ascidoc HTML, we copy it to the mlreef.jar. This way we can host it statically on the application server under
...:8080/{some path}/index.html
-
As an experiment, we add Swagger Documentation to the project. This will give especially FE developers some additional tools and freedom.
Permissions and Security
The documentation should be accessible for everyone without login.
Also Swagger shall be accessible for everyone without login.
Documentation
It is possible that this list is outdated -> please update the TODOs accordingly.
-
Add documentation to the README.md on where to find and how to use the API documentation.
Broken sections in the Rest-Docs
-
Projects - /projects, practically all this part is failing. -
CodeProjects - /code-projects - The next Data project sections:
-
GET /data-projects -
GET /data-projects/public -
GET /data-projects/:id -
POST /data-projects -
PUT /data-projects/:id -
DELETE /data-projects/:id -
GET /data-projects/:id/users and the next ones: -
POST /data-projects/:id/users? -
POST /data-projects/:id/users -
DELETE /data-projects/:id/users/:userId -
DELETE /data-projects/:id/users?
-
-
POST …/experiments/:id/start -
All the EPF Experiments
section
Availability & Testing
As an API consumer, I should be able to find the documentation available and up-to-date most of the time
/cc @si-ge-st