REST API documentation consistency improvements

[alexvuka1]

I have identified the following possible instances of inconsistencies between Open API specification and Documentation:

• 🟩Found in Open API specification, 🟥Not found in Documentation

  • GET /v1/graph/{graph_id}/vertex
  • PUT /v1/graph/{graph_id}/vertex
  • POST /v1/graph/{graph_id}/vertex
  • DELETE /v1/graph/{graph_id}/vertex
  • GET /v1/graph/{graph_id}/edge
  • PUT /v1/graph/{graph_id}/edge
  • POST /v1/graph/{graph_id}/edge
  • DELETE /v1/graph/{graph_id}/edge
  • POST /v1/graph/{graph_id}/query
  • GET /v1/graph/{graph_id}

• 🟥Not found in Open API specification, 🟩Found in Documentation

  • GET /v1/node/status

• 🟩Found in Open API specification, 🟩Found in Documentation, 🟥Have Inconsistencies

  • Inconsistency type	Open API specification DELETE /v1/graph/{graph_id}	Documentation DELETE /v1/graph/{graph}
    Path parameter name mismatch	graph_id	graph

  • Inconsistency type	Open API specification GET /v1/graph/{graph_id}/schema	Documentation GET /v1/graph/{graph}/schema
    Path parameter name mismatch	graph_id	graph

  • Inconsistency type	Open API specification POST /v1/graph/{graph_id}/dataloading	Documentation POST /v1/graph/{graph}/dataloading
    Path parameter name mismatch	graph_id	graph

  • Inconsistency type	Open API specification GET /v1/graph/{graph_id}/procedure	Documentation GET /v1/graph/{graph}/procedure
    Path parameter name mismatch	graph_id	graph

  • Inconsistency type	Open API specification POST /v1/graph/{graph_id}/procedure	Documentation POST /v1/graph/{graph}/procedure
    Path parameter name mismatch	graph_id	graph

  • Inconsistency type	Open API specification GET /v1/graph/{graph_id}/procedure/{procedure_id}	Documentation GET /v1/graph/{graph}/procedure/{proc_name}
    Path parameter name mismatch	graph_id	graph
    Path parameter name mismatch	procedure_id	proc_name

  • Inconsistency type	Open API specification PUT /v1/graph/{graph_id}/procedure/{procedure_id}	Documentation PUT /v1/graph/{graph}/procedure/{proc_name}
    Path parameter name mismatch	graph_id	graph
    Path parameter name mismatch	procedure_id	proc_name

  • Inconsistency type	Open API specification DELETE /v1/graph/{graph_id}/procedure/{procedure_id}	Documentation DELETE /v1/graph/{graph}/procedure/{proc_name}
    Path parameter name mismatch	graph_id	graph
    Path parameter name mismatch	procedure_id	proc_name

  • Inconsistency type	Open API specification POST /v1/service/stop	Documentation GET /v1/service/stop
    Method mismatch	POST	GET

About

This is part of the evaluation of my Master's Project at Imperial College London. The section above is automatically generated and aims to expose API documentation inconsistencies in real-world GitHub repositories. The end goal is for the tool to be used as part of CI/CD, namely as a GitHub action.

Hopefully, this is a step towards easier maintenance of API documentation. If you find this helpful, please consider updating the documentation to keep it in sync with the source code. I am also happy to assist with it, if appropriate. If this has not been useful, consider updating this issue with an explanation, so I can improve my approach. Thank you!

[welcome]

Thanks for opening your first issue here! Be sure to follow the issue template! And a maintainer will get back to you shortly!
Please feel free to contact us on DingTalk, WeChat account(graphscope) or Slack. We are happy to answer your questions responsively.

[yecol]

hi @alexvuka1, thanks for reporting!
We plan to evolve the interface for clients (SDK/Restful/Python) from gRPC to Restful APIs.
Currently we are developing the OpenAPI related functions actively, hence you may find the docs missing.
Please stay tuned, and we will keep you updated when the OpenAPI is beta available. /cc @lidongze0629
Thank you again!

[alexvuka1]

Hi @yecol, that's good to know. Would it be useful to get reports such as the one in the description during the development of the REST API? For example, to track the progress of the documentation process. The aim of the project is to be used iteratively during development (as a GitHub action), so it would be interesting to hear your opinion on this. Thanks!