weso/rdfshape-api

Update Swagger documentation about the API

labra opened this issue · 2 comments

labra commented

The API documentation has not been updated and there are several services that are not documented in swagger:

https://app.swaggerhub.com/apis-docs/labra/rdfshape/1.0.1

Notice that the client points to this documentation in the Help -> API Documentation.

One problem is that the server is hidden in the 8080 port and now it uses https instead of http.

For example, instead of:

http://rdfshape.weso.es/api/schema/engines

it should point to:

https://rdfshape.weso.es:8080/api/schema/engines

I consider this issue a good chance for rearranging the way we maintain RDFShape API docs. It's about time we had a clean and updated API documentation if we want to promote this tool.
I'm willing to:

  1. Review the API responses of RDFShape and change the status-codes of the responses to more descriptive ones if necessary.
  2. Refactor RDFShape using Rho to document the API from the code itself and have a swagger.json file generated automatically. I noticed Rho is a niche tool with limited documentation, so I'll update this issue in case problems arise.
  3. Setup an automated CI pipeline that updates the API docs in SwaggerHub whenever changes are pushed to the repository.

Detailed and updated API docs are automatically generated and publicly available in SwaggerHub, see #292

We are lacking some automated testing tools plus there are no easy means to automatically push changes to SwaggerHub, so updates to the public API Docs must be performed manually for the best.