Convert route_setting :tier to x-gitlab-tier OpenAPI annotation

Overview

As part of the OpenAPI Annotations - REST Endpoint Tier epic, we need to register :tier in the gitlab-grape-openapi gem's annotations configuration so that route_setting :tier, :ultimate (or :premium) on any EE Grape endpoint emits x-gitlab-tier: "ultimate" in the generated OpenAPI YAML.

This is the foundational backend issue — the same pattern as how x-gitlab-lifecycle was implemented in !225472 (merged).

Background

The gitlab-grape-openapi gem already supports a generic annotation pipeline:

  1. config.annotations in config/initializers/gitlab_grape_openapi.rb maps route_setting keys to OpenAPI extension keys.
  2. OperationConverter#extract_annotations reads options[:settings] and emits those keys as OpenAPI extensions on each operation.
  3. Operation#to_h injects them at the top level of the operation object.

Adding x-gitlab-tier requires only registering the mapping — no changes to the converter or model are needed.

Proposal

1. Register the annotation mapping

In config/initializers/gitlab_grape_openapi.rb, add to the config.annotations hash:

config.annotations = {
  lifecycle: 'x-gitlab-lifecycle',
  tier: 'x-gitlab-tier'             # ← add this line
}

2. Add example annotations to EE API files

Add route_setting :tier declarations to a small number of EE endpoints to validate end-to-end, for example:

# ee/lib/api/epics.rb
route_setting :tier, :premium
desc 'Get epics for the group' do
  ...
end
get ...
# ee/lib/api/audit_events.rb
route_setting :tier, :premium
desc 'Get a list of audit events' do
  ...
end
get ...

3. Regenerate the OpenAPI spec

Run bin/rake gitlab:openapi:v3:generate and confirm x-gitlab-tier appears correctly in the output YAML for annotated endpoints, and is absent for CE endpoints.

Acceptance Criteria

  • tier: 'x-gitlab-tier' added to config.annotations in the initializer
  • route_setting :tier, :premium → x-gitlab-tier: "premium" in generated spec
  • route_setting :tier, :ultimate → x-gitlab-tier: "ultimate" in generated spec
  • Unannotated (CE) endpoints have no x-gitlab-tier key in the spec
  • At least two EE API files have example route_setting :tier declarations
  • Gem specs updated/added to cover the new annotation key
  • OpenAPI spec regenerated and committed

Related

Edited by 🤖 GitLab Bot 🤖