Decide on OpenAPI 3.0 autogeneration method

Problem Statement

• Currently Grape can (and does) autogenerate an OpenAPI 2.0 doc which is statically generated, and available at https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/openapi/openapi_v2.yaml.
• The pipeline fails if the OpenAPI specification is not generated.
• There is an OpenAPI 3.0 spec which is not autogenerated, available doc/api/openapi/openapi.yaml. This file has seen 3 commits since the start of 2025.
• The OpenAPI 2.0 spec is auto-generated from the Grape API definitions inside the GitLab Rails monolith. A method of directly generating an OpenAPI 3.0 specification from a GrapeAPI does not appear to exist currently. Methods of automatically generating an OpenAPI 3.0 spec from an OpenAPI 2.0 specification do exist, but are not well maintained.

This issue will propose a few potential implementations to move GitLab's REST API to OpenAPI 3.0 by-default, including a method of automatically generating the OpenAPI 3.0 spec from the Grape API definitions.

Current status 👋

Soliciting feedback from engineering stakeholders about our proposed plan for the next few weeks.