Annotate REST APIs and Fields with lifecycle attributes

From the decision made at the FY26Q1 Tech Summit "Rethink our approach to maintaining our APIs (REST + GraphQL)" session -- documented in https://docs.google.com/document/d/1VNB3ivS9aCJc-fck1TLP48pzFYRsEPASLijn9ufXctY/edit?tab=t.2fcx3kdhhtj#bookmark=id.djz9l4fdc97u:

---

We are planning on switching to OpenAPI-specific REST schemas (related to gitlab-com/engineering-division/engineering#45 (closed) and &5792).

As part of this, we will introduce lifecycle annotations on REST APIs, the input parameters and fields, and output parameters.

These can be one of:

1. experimental
2. beta
3. stable
4. internal

These annotations will have differing guarantees for API stability, allowing early experimentation while ensuring stability once the API is well understood.

Since the OpenAPI specification is generated from the Grape configuration in Ruby, these annotations will need to be added in Ruby too.

On the OpenAPI end, this could be specified using OpenAPI Extensions: https://swagger.io/docs/specification/v2_0/swagger-extensions/

experimental and internal APIs/parameters/fields should not be documentation, and beta should be opt-in, or published to a different site (eg, beta.docs.gitlab.com)

Related to API Team: Invest in a team which owns REST and ... (gitlab-com/engineering-division/engineering#45 - closed)

cc @m_frankiewicz