## Problem Statement As part of our work to surface GitLab-specific attributes in our OpenAPI documentation, we want to annotate REST API endpoints with their minimum required paid tier (Free, Premium, or Ultimate) and surface this information in our public OpenAPI/Scalar documentation. Currently, tier information is either absent from endpoint definitions or mentioned inconsistently in free-text `desc` blocks (e.g., "This endpoint is available on Premium and above"). This makes it impossible to generate accurate, machine-readable tier information in our OpenAPI spec. In the current markdown docs, this looks like: {width=760 height=156} ## DRI - @mwoolf ## Approach - Only EE endpoints need explicit annotation. CE endpoints are implicitly Free. - Tier is declared as the **minimum required tier** using `route_setting :tier, :ultimate` or `route_setting :tier, :premium`. - Valid declared values are `:premium` and `:ultimate` only (symbols, not strings). `:free` is implicit and not a valid declared value. - The `x-gitlab-tier` OpenAPI extension is generated from the `route_setting` value. - The Scalar frontend component displays **all tiers the endpoint is available in**, with tiers below the minimum greyed out (e.g., `x-gitlab-tier: "ultimate"` shows Free · Premium · **Ultimate**). ## Exit Criteria - [ ] `route_setting :tier, :ultimate` / `:premium` on EE Grape endpoints converts to `x-gitlab-tier` in the generated OpenAPI spec. - [ ] A Scalar plugin badge component displays tier availability for each endpoint (defaulting to Free when `x-gitlab-tier` is absent). - [ ] A RuboCop cop (`API::RouteSettingTier`) enforces only `:premium` and `:ultimate` symbols are used as values. - [ ] A RuboCop cop (`API::TierInDescription`) blocks ad-hoc tier language in free-text `desc`/`detail` blocks. - [ ] Developer documentation updated to reference the new `route_setting :tier` convention. ## Issues - [#593084](https://gitlab.com/gitlab-org/gitlab/-/issues/593084) - Convert `route_setting :tier` to `x-gitlab-tier` OpenAPI annotation - [#593085](https://gitlab.com/gitlab-org/gitlab/-/issues/593085) - Create custom Endpoint Tier plugin component for Scalar API documentation - [#593086](https://gitlab.com/gitlab-org/gitlab/-/issues/593086) - Add RuboCop cop to enforce valid `route_setting :tier` values - [#593087](https://gitlab.com/gitlab-org/gitlab/-/issues/593087) - Add RuboCop cop to block tier keywords in REST endpoint descriptions ## Related - Parent epic: [DevEx: API Platform](https://gitlab.com/groups/gitlab-org/quality/-/work_items/200) - Sibling epic: [OpenAPI Annotations - REST Endpoint Lifecycle](https://gitlab.com/groups/gitlab-org/quality/-/epics/316) <!-- STATUS NOTE START --> ## Status 2026-07-30 Work resumed on this epic now that other priorities have been settled. :tada: **achievements**: - Opened a MR that adds the `x-gitlab-tier` annotation, and sets the tier to the first 2 routes! :issue-blocked: **blockers**: - :arrow_forward: **next**: - Close the MR, annotate more routes, and start working on other child issues _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/366#note_3621913932_ <!-- STATUS NOTE END -->