Merge branch 'document-openapi-vision' into 'master'

Add vision for GitLab OpenAPI documentation

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113727



Merged-by: Andy Soiron <asoiron@gitlab.com>
Approved-by: Urvi Chetta <uchetta@gitlab.com>
Co-authored-by: Urvi Chetta <uchetta@gitlab.com>

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.
 
 ![API viewer screenshot](img/apiviewer03-fs8.png)
+
+## 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).