roksys
commented
6 years ago @tiborsimko, about third bullet. I am not sure about using endpoint url as a title. Some urls are too long and won't fit to a left menu. Please take a look at the attached image.
The REST API documentation navigation can be improved:
Harmonise tile text in Python docstring and OpenAPI. Example: https://reana-workflow-controller.readthedocs.io/en/latest/restapi.html we have "Get all workflows" but in https://reana-workflow-controller.readthedocs.io/en/latest/_static/api.html#operation/get_workflows we have "Returns all workflows". Harmonising Python and OpenAPI headlines will help smoother navigation.
Some titles are too long and the navigation does not lead to the target. Example: "Create a new cwl workflow from a remote repository" does not point to the correct anchor. A quick solution would be to simply shorten the docstring/openapi title sentence to N characters. A longer solution would be investigate how to influence anchor generation, if at all possible.
We can also envisage using
/api/workflows/{id}as the docstring/openapi title text. It is short, and the generated documentation will be URI oriented, which is not bad to get a quick overview. The rest of the documentation can start with "Get all workflows..." and other such longer explanations. We could experiment whether this would be OK.It would be good to go through all the endpoints and check the title text consistency and anchor navigation in the above sense.