Open alexvuka1 opened 4 months ago
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!
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!
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
DELETE /v1/graph/{graph_id}
DELETE /v1/graph/{graph}
graph_id
graph
GET /v1/graph/{graph_id}/schema
GET /v1/graph/{graph}/schema
graph_id
graph
POST /v1/graph/{graph_id}/dataloading
POST /v1/graph/{graph}/dataloading
graph_id
graph
GET /v1/graph/{graph_id}/procedure
GET /v1/graph/{graph}/procedure
graph_id
graph
POST /v1/graph/{graph_id}/procedure
POST /v1/graph/{graph}/procedure
graph_id
graph
GET /v1/graph/{graph_id}/procedure/{procedure_id}
GET /v1/graph/{graph}/procedure/{proc_name}
graph_id
graph
procedure_id
proc_name
PUT /v1/graph/{graph_id}/procedure/{procedure_id}
PUT /v1/graph/{graph}/procedure/{proc_name}
graph_id
graph
procedure_id
proc_name
DELETE /v1/graph/{graph_id}/procedure/{procedure_id}
DELETE /v1/graph/{graph}/procedure/{proc_name}
graph_id
graph
procedure_id
proc_name
POST /v1/service/stop
GET /v1/service/stop
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!