## Closing statement All Redocly validation errors and warnings have been solved. GitLab's OpenAPI 3.0 specification is now compliant with Redocly's recommended configuration, and thus easier to understand and digest by both humans agents. The work has also allowed the team to surface, and solve, other issues with the quality of GitLab's API and OpenAPI 3.0 specification generator gem ## Goal Burn down all Redocly (industry standard API documentation tool) validation errors and warnings to get the OpenAPI 3.0 specification into the best possible shape by having it comply with Redocly's recommended configuration. ## DRI @abignotti ## Context As discussed in [#591007 (note 3137603023)](https://gitlab.com/gitlab-org/gitlab/-/issues/591007#note_3137603023), the team agreed to adopt [Redocly CLI](https://github.com/redocly/redocly-cli) as the OpenAPI specification validator (replacing the unmaintained `swagger-cli`). Running Redocly with the `recommended` configuration against the current spec produces **553 errors** and **1,082 warnings**. The validation is being added in [gl-infra/api-docs!31](https://gitlab.com/gitlab-com/gl-infra/api-docs/-/merge_requests/31), with error rules initially overridden to warnings for an incremental approach. This epic tracks the work to resolve all issues and remove those overrides. ## Error Summary (Redocly `recommended` config) ### Errors (553) | Rule | Count | Description | |------|-------|-------------| | `path-parameters-defined` | 540 | Operations missing path parameter definitions | | `operation-operationId-url-safe` | 8 | operationId contains non-URL-safe characters | | `operation-summary` | 2 | Operations missing `summary` | | `no-identical-paths` | 2 | Duplicate paths differing only by param name | | `no-server-trailing-slash` | 1 | Server URL has trailing slash | ### Warnings (1,082) | Rule | Count | Description | |------|-------|-------------| | `operation-4xx-response` | 692 | Missing 4xx error responses | | `no-invalid-parameter-examples` | 120 | Parameter examples don't match schema | | `no-invalid-schema-examples` | 96 | Schema examples don't match schema | | `no-ambiguous-paths` | 76 | Ambiguous path templates | | `no-unused-components` | 64 | Unused schema components | | `operation-2xx-response` | 33 | Missing 2xx responses | | `info-license` | 1 | Missing license info | <!-- STATUS NOTE START --> ## Status 2026-05-28 :clock1: **total hours spent this week by all contributors**: 16 hours :tada: **achievements**: - @abignotti and @vwolanyk managed to burn down the last of the issues related to this epic - there is only one last MR awaiting one more review and ready to merge before we can close the issue :issue-blocked: **blockers**: - :arrow_forward: **next**: - This epic should be closed within the next day or 2 _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/363#note_3392208380_ <!-- STATUS NOTE END -->