## Problem Statement [OpenAPI Annotations - REST Endpoint Tier](https://gitlab.com/groups/gitlab-org/quality/-/epics/366) made an endpoint's minimum paid tier machine-readable via `route_setting :tier` → `x-gitlab-tier`. The same information exists one level down, on individual **parameters**, and is still trapped in free text. Two dimensions are affected: - **Tier** — a parameter that only takes effect on Premium or Ultimate. For example `lib/api/ci/job_artifacts.rb` declares `:job_token` five times with `desc: '... available only on Premium and Ultimate tiers.'` - **Role** — a parameter only honoured for administrators. For example `lib/api/projects.rb` declares `repository_storage` as `desc: '... Available only to admins'` and `include_pending_delete` as `desc: '... Can only be set by admins'`. Neither is expressible today, so neither reaches the OpenAPI spec or Scalar. A reader sees a parameter they cannot actually use, with the caveat buried in prose — or, more often, not present in the spec at all, because the caveat only ever made it into the hand-written Markdown reference. In the Markdown reference this is already documented at attribute level, at scale: **155 distinct parameters** carry a Premium/Ultimate note and **43** carry an administrator note, across **58** files under `doc/api/`. ## DRI - @mwoolf ## Approach - Annotations are declared per parameter inside Grape's `documentation:` hash, the only free-form carrier Grape offers. Any other key is looked up as a validator name and raises `Grape::Exceptions::UnknownValidator`. ```ruby optional :job_token, type: String, desc: 'CI/CD job token for multi-project pipelines.', documentation: { tier: :premium } ``` - A new `config.parameter_annotations` in the gem maps `documentation:` keys to OpenAPI extension names, mirroring the existing route-level `config.annotations`: ```ruby config.parameter_annotations = { tier: 'x-gitlab-tier', role: 'x-gitlab-role' } ``` - `x-gitlab-tier` keeps the meaning and vocabulary it has at endpoint level: minimum required tier, `premium` or `ultimate` only, `free` implicit. At parameter level it **narrows** — a parameter needs the higher of its own tier and its endpoint's. - Scope is limited to **gated** parameters: the parameter is rejected or ignored without the tier or role. Parameters whose *behaviour* merely widens at a higher tier (for example `lib/api/releases.rb` `milestones`, where Premium customers may additionally pass group milestones) stay in prose — a flag on the parameter would assert something false. - Both extensions are emitted in two places, because Grape parameters land in two different OpenAPI objects: query and path parameters become Parameter Objects, while POST/PUT body parameters become properties inside a `RequestBody_*` schema. OpenAPI 3.0 permits `x-` extensions on both, and `yarn swagger:validate` (swagger-cli 4.0.4) accepts both — verified against a minimal spec, with a non-`x-` control correctly rejected. ### Open question: the `role` vocabulary `tier` maps cleanly onto the existing `premium` / `ultimate` vocabulary. `role` does not, and the epic should not pretend otherwise. Auditing `lib/api` and `ee/lib/api`, parameters with a **compound** role requirement outnumber cleanly administrator-only ones roughly two to one: | | Examples | |---|---| | Administrator only | `projects.rb` `repository_storage`, `include_pending_delete`; `helpers/projects_helpers.rb` `repository_storage` | | Compound | `issues.rb` `created_at`, `iid`, `updated_at` ("admins and project owners"); `ee/lib/api/epics.rb` `created_at`, `updated_at`; `helpers/work_items/create_params.rb` `created_at`; `group_service_accounts.rb` ("group Owners and administrators"); `project_service_accounts.rb` ("project Owners, Maintainers, and administrators") | The Markdown reference shows the same shape — 26 rows read "Requires administrator or project/group owner rights". A single `role: :administrator` enum cannot express those, and flattening them to `:administrator` would be **wrong**, not merely lossy: it would tell readers that a project owner cannot use a parameter they can in fact use. The mechanism is dimension-agnostic, so this does not block it. The decision to make is whether `role` ships with a richer vocabulary, ships restricted to the clean administrator-only cases with compound ones left in prose, or is deferred to a follow-up epic. **Tier is the confident half of this epic; role is provisional.** ## Exit Criteria - [ ] `documentation: { tier: }` / `{ role: }` on a Grape parameter emits `x-gitlab-tier` / `x-gitlab-role` in the generated OpenAPI spec, for both query and request-body parameters. - [ ] Scalar displays tier and role availability on individual parameter rows. - [ ] A RuboCop cop enforces valid parameter tier and role values. - [ ] The `role` vocabulary question above is resolved and recorded. - [ ] A RuboCop cop blocks ad-hoc tier and administrator language in parameter `desc:` strings. - [ ] Developer documentation covers the parameter-level convention and its precedence relative to endpoint-level `route_setting :tier`. - [ ] The parameters currently documented as tier- or administrator-restricted in the Markdown reference are annotated in the Grape source. ## Issues - [gitlab-grape-openapi#32](https://gitlab.com/gitlab-org/ruby/gems/gitlab-grape-openapi/-/issues/32) - Add parameter-level annotation support - [#630309](https://gitlab.com/gitlab-org/gitlab/-/issues/630309) - Wire up parameter-level OpenAPI annotations and document the convention - [#630310](https://gitlab.com/gitlab-org/gitlab/-/issues/630310) - Annotate tier- and role-restricted parameters already declared in the Grape source - [#630311](https://gitlab.com/gitlab-org/gitlab/-/issues/630311) - Display parameter tier and role in the Scalar API reference - [#630312](https://gitlab.com/gitlab-org/gitlab/-/issues/630312) - Add RuboCop cop to enforce valid parameter tier and role values - [#630313](https://gitlab.com/gitlab-org/gitlab/-/issues/630313) - Add RuboCop cop to block tier and administrator keywords in parameter descriptions - [#630314](https://gitlab.com/gitlab-org/gitlab/-/issues/630314) - Backfill parameter tier and role annotations from the Markdown reference ## Related - Parent epic: [DevEx: API Platform](https://gitlab.com/groups/gitlab-org/quality/-/work_items/200) - Sibling epic: [OpenAPI Annotations - REST Endpoint Tier](https://gitlab.com/groups/gitlab-org/quality/-/epics/366) - Sibling epic: [Introduce Lifecycle Status to REST API](https://gitlab.com/groups/gitlab-org/quality/-/epics/316) ### Note on gem versioning `x-gitlab-tier` at endpoint level shipped in `gitlab-grape-openapi` 0.2.3, which is the version currently pinned in the monolith. The parameter-level work in this epic needs a **further** gem release; it is not already in flight.