Merge branch 'winniehell-openapi-mvc' into 'master'

Add OpenAPI specification for GitLab API

See merge request gitlab-org/gitlab!35868

changelogs/unreleased/winniehell-openapi-mvc.yml

+---
+title: Add first OpenAPI specification file
+merge_request: 35868
+author: winniehell
+type: other

doc/api/README.md

@@ -4,6 +4,8 @@ Automate GitLab via a simple and powerful API.
 
 The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts.
 
+There is also a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/api/openapi/openapi.yaml), which allows you to test the API directly from the GitLab user interface. Contributions are welcome.
+
 ## Available API resources
 
 For a list of the available resources and their endpoints, see

doc/api/openapi/openapi.yaml

+openapi: "3.0.0"
+info:
+  description: |
+    An OpenAPI definition for the GitLab REST API.
+    Only one API resource/endpoint is currently included.
+    The intent is to expand this to match the entire Markdown documentation of the API:
+    <https://docs.gitlab.com/ee/api/>. Contributions are welcome.
+
+    When viewing this on gitlab.com, you can test API calls directly from the browser
+    against the `gitlab.com` instance, if you are logged in.
+    The feature uses the current [GitLab session cookie](https://docs.gitlab.com/ee/api/README.html#session-cookie),
+    so each request is made using your account. 
+
+    Read more at <https://docs.gitlab.com/ee/development/documentation/styleguide.html#restful-api>.
+  version: "v4"
+  title: "GitLab API"
+  termsOfService: "https://about.gitlab.com/terms/"
+  license:
+    name: "CC BY-SA 4.0"
+    url: "https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE"
+servers:
+  - url: "https://gitlab.com/api/"
+
+paths:
+  /v4/version:
+    $ref: "v4/version.yaml"

doc/api/openapi/v4/version.yaml

+# Markdown documentation: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/version.md
+
+get:
+  tags:
+    - version
+  summary: "Retrieve version information for this GitLab instance."
+  operationId: "getVersion"
+  responses:
+    "401":
+      description: "unauthorized operation"
+    "200":
+      description: "successful operation"
+      content:
+        "application/json":
+          schema:
+            title: "VersionResponse"
+            type: "object"
+            properties:
+              version:
+                type: "string"
+              revision:
+                type: "string"
+          examples:
+            Example:
+              value:
+                version: "13.3.0-pre"
+                revision: "f2b05afebb0"
+

doc/development/api_styleguide.md

@@ -13,10 +13,12 @@ Always use an [Entity](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/
 
 ## Documentation
 
-API endpoints must come with [documentation](documentation/styleguide.md#restful-api), unless it is internal or behind a feature flag.
+Each new or updated API endpoint must come with documentation, unless it is internal or behind a feature flag.
 The docs should be in the same merge request, or, if strictly necessary,
 in a follow-up with the same milestone as the original merge request.
 
+See the [Documentation Style Guide RESTful API section](documentation/styleguide.md#restful-api) for details on documenting API resources in Markdown as well as in OpenAPI definition files.
+
 ## Methods and parameters description
 
 Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods)

doc/development/documentation/styleguide.md

@@ -1738,8 +1738,13 @@ For guidance on developing GitLab with feature flags, see
 
 ## RESTful API
 
-Here is a list of must-have items for RESTful API documentation. Use them in the
-exact order that appears on this document. Further explanation is given below.
+REST API resources are documented in Markdown under [`/doc/api`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api). Each resource has its own Markdown file, which is linked from `api_resources.md`.
+
+When modifying the Markdown, also update the corresponding [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi) if one exists for the resource.
+If not, consider creating one. Match the latest [OpenAPI 3.0.x specification](https://swagger.io/specification/).
+(For more information, see the discussion in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16023#note_370901810).)
+
+In the Markdown doc for a resource (AKA endpoint):
 
 - Every method must have the REST API request. For example: