diff options
Diffstat (limited to 'doc/api/openapi/openapi_interactive.md')
| -rw-r--r-- | doc/api/openapi/openapi_interactive.md | 10 |
1 files changed, 10 insertions, 0 deletions
diff --git a/doc/api/openapi/openapi_interactive.md b/doc/api/openapi/openapi_interactive.md index c3e3f5f372b..2185f5b493e 100644 --- a/doc/api/openapi/openapi_interactive.md +++ b/doc/api/openapi/openapi_interactive.md @@ -48,3 +48,13 @@ by the server responses that are returned. You can create new responses by editi and then select **Execute** once again.  + +## Vision + +The API code is the single source of truth, and the API documentation should be tightly coupled to its implementation. The OpenAPI specification provides a standardized and comprehensive way to document APIs. It should be the go-to format for documenting the GitLab REST API. This will result in more accurate, reliable, and user-friendly documentation that enhances the overall experience of using the GitLab REST API. + +To achieve this it should be a requirement to update the OpenAPI specification with every API code change. By doing so, we ensure that the documentation is always up-to-date and accurate, reducing the risk of confusion as well as errors for our users. + +The OpenAPI documentation should be autogenerated from the API code, so that it is easy to keep it up to date and accurate. This will save time and effort for our documentation team. + +You can follow the current progress of this vision in the [Document the REST API in OpenAPI V2 epic](https://gitlab.com/groups/gitlab-org/-/epics/8926). |