## Closing Statement The epic was created to allow the [gitlab-grape-openapi](https://gitlab.com/gitlab-org/gitlab/-/tree/master/gems/gitlab-grape-openapi) gem, the gem that generates the OpenAPI 3.0-compliant specification for GitLab's whole API, to support all Grape DSL keywords. Previously, endpoints using unsupported keywords missed information in our generated API specification. All keywords are now covered by the gem (even ones that are unused in our codebase, thanks to community contributions by students from a program team members joined), with linters ensuring future changes to API endpoints follow conventions. ## DRI @abignotti ## Participants @vwolanyk ## Context The `gitlab-grape-openapi` gem, our internal gem that generates the OpenAPI 3.0 specification, does not support a few of Grape's keywords that are all used in GitLab's API. For reference, these are all of Grape's keywords, alongside their status as of the 19th of January 2026: | Option | Description | Supported? | Occurrences in GitLab API | |--------|-------------|------------|---------------------------| | `type` | Data type (String, Integer, Boolean, Array, Hash, etc.) | :white_check_mark: Supported | 2000+ (search API limit reached) | | `types` | Multiple allowed types (mutually exclusive with `type`) | :x: Missing | 143 | | `default` | Default value (can be a Proc) | :white_check_mark: Supported | 2000+ (search API limit reached) | | `desc` / `description` | Description text | :white_check_mark: Supported | 2000+ (search API limit reached) | | `regexp` | Regex validation | :white_check_mark: Supported (via validations) | 87 | | `values` | Allowed values (Array, Range, or Proc) | :white_check_mark: Supported | 2000+ (search API limit reached) | | `except_values` | Disallowed values (Array, Range, or Proc with arity 0) | :x: Missing | 2 | | `allow_blank` | Allow blank/nil values (default: true for optional) | :x: Missing | 97 | | `coerce_with` | Custom coercion lambda/proc | :x: Missing | 100 | | `as` | Rename parameter internally | :white_check_mark: Supported | 28 | | `documentation` | Hash for grape-swagger (keys: `type`, `desc`, `param_type`, `is_array`, `format`, `example`, `required`) | :white_check_mark: Supported | 2000+ (search API limit reached) | | `fail_fast` | Stop validation on first error for this param | :x: Missing | 0 | | `same_as` | Must match another parameter's value | :x: Missing | 1 | | `length` | String/Array length validation (`is`, `min`, `max`) | :x: Missing | 0 | | `message` | Custom validation error message | :x: Missing | 1 | > **Note (2026-02-09):** The "Occurrences in GitLab API" column was generated by searching the `gitlab-org/gitlab` codebase under `lib/api/` and `ee/lib/api/` for each Grape keyword used in parameter definitions. Counts marked "2000+ (search API limit reached)" indicate the keyword appears in more than 2,000 search results, which is the maximum the GitLab search API can return (20 pages × 100 results). For precise counts of those keywords, a local `grep` on the repository would be needed. ## Goal Add support to all of Grape's keywords, ensuring that they get "translated" into the proper objects in the OAPI 3.0 specification. ## Why? 1. GitLab's REST API uses many/all of these Grape keywords for validation and documentation. Without full support, the generated OpenAPI 3.0 specification could be inaccurate 2. Missing keyword support can lead to confusion and integration errors for internal and/or external developers 3. Helps have parity between what Grape validates at runtime and what the OpenAPI specification documents ## Proposed Solution Extend the `ParameterConverter` and `ParameterSchema` classes to map each Grape keyword to its OAPI 3.0 equivalent: - `regexp` → `pattern` in schema - `values` → `enum` in schema - `default` → `default` in schema - `length` → `minLength`/`maxLength` in schema - `allow_blank` → `nullable` in schema - `types` → `oneOf` or `anyOf` in schema - `documentation` → extract additional OpenAPI properties ## Success Criteria 1. All Grape keywords used in GitLab's API are supported 2. Generated OpenAPI 3.0 specification accurately reflects all parameter constraints 3. Validation rules in Grape match constraints in OpenAPI schema 4. No loss of information when converting from Grape DSL to OAPI 3.0 <!-- STATUS NOTE START --> ## Status 2026-04-30 :clock1: **total hours spent this week by all contributors**: 1h :tada: achievements: * Shepherded the last 2 student community contributions for the last unsupported keywords (hhttps://gitlab.com/gitlab-org/gitlab/-/merge_requests/228360, https://gitlab.com/gitlab-org/gitlab/-/merge_requests/228387) :issue-blocked: blockers: * :arrow_forward: next: * Grand Reviewers to close the epic! _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/321#note_3302583801_ <!-- STATUS NOTE END -->