alibaba / alibaba/GraphScope

REST API documentation consistency improvements

Open
#3,809 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
3.6k
Forks
468
Avg merge
29m
Merged PRs (30d)
1

Description

I have identified the following possible instances of inconsistencies between [Open API specification](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) and [Documentation](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md):

- ### 🟩Found in Open API specification, 🟥Not found in Documentation
- [ ] [`GET /v1/graph/{graph_id}/vertex`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`PUT /v1/graph/{graph_id}/vertex`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`POST /v1/graph/{graph_id}/vertex`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`DELETE /v1/graph/{graph_id}/vertex`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`GET /v1/graph/{graph_id}/edge`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`PUT /v1/graph/{graph_id}/edge`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`POST /v1/graph/{graph_id}/edge`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`DELETE /v1/graph/{graph_id}/edge`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`POST /v1/graph/{graph_id}/query`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- [ ] [`GET /v1/graph/{graph_id}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml)
- ### 🟥Not found in Open API specification, 🟩Found in Documentation
- [ ] [`GET /v1/node/status`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L28)
- ### 🟩Found in Open API specification, 🟩Found in Documentation, 🟥Have Inconsistencies
- | Inconsistency type | Open API specification
[`DELETE /v1/graph/{graph_id}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`DELETE /v1/graph/{graph}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L17) |
| --- | --- | --- |
| Path parameter name mismatch | `graph_id` | `graph` |
- | Inconsistency type | Open API specification
[`GET /v1/graph/{graph_id}/schema`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`GET /v1/graph/{graph}/schema`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L15) |
| --- | --- | --- |
| Path parameter name mismatch | `graph_id` | `graph` |
- | Inconsistency type | Open API specification
[`POST /v1/graph/{graph_id}/dataloading`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`POST /v1/graph/{graph}/dataloading`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L18) |
| --- | --- | --- |
| Path parameter name mismatch | `graph_id` | `graph` |
- | Inconsistency type | Open API specification
[`GET /v1/graph/{graph_id}/procedure`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`GET /v1/graph/{graph}/procedure`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L20) |
| --- | --- | --- |
| Path parameter name mismatch | `graph_id` | `graph` |
- | Inconsistency type | Open API specification
[`POST /v1/graph/{graph_id}/procedure`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`POST /v1/graph/{graph}/procedure`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L19) |
| --- | --- | --- |
| Path parameter name mismatch | `graph_id` | `graph` |
- | Inconsistency type | Open API specification
[`GET /v1/graph/{graph_id}/procedure/{procedure_id}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`GET /v1/graph/{graph}/procedure/{proc_name}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L21) |
| --- | --- | --- |
| 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}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`PUT /v1/graph/{graph}/procedure/{proc_name}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L23) |
| --- | --- | --- |
| 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}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`DELETE /v1/graph/{graph}/procedure/{proc_name}`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L22) |
| --- | --- | --- |
| Path parameter name mismatch | `graph_id` | `graph` |
| Path parameter name mismatch | `procedure_id` | `proc_name` |
- | Inconsistency type | Open API specification
[`POST /v1/service/stop`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/flex/openapi/openapi_interactive.yaml) | Documentation
[`GET /v1/service/stop`](https://github.com/alibaba/GraphScope/blob/bf4bd712041a04ce3adba56939a5bccaad13e137/docs/flex/interactive/development/restful_api.md?plain=1#L26) |
| --- | --- | --- |
| 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!

Contributor guide

Open the contributing guide

Research direction

Compare flex/openapi/openapi_interactive.yaml with docs/flex/interactive/development/restful_api.md, starting with the listed endpoint entries and parameter names. Reconcile the documented paths and methods with the OpenAPI specification, including missing endpoints, then verify every inconsistency in the issue checklist is resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.