## DRI `@cfeick` ## Participants - `@mwoolf` - `@abignotti` - `@idurham` - `@kkloss` ## Problem statement GitLab's [REST API documentation](https://docs.gitlab.com/api/api_resources/) was previously limited to manually maintained Markdown pages that covered only a subset of the REST API. The OpenAPI 2.0 specification was incomplete and did not include the entire API surface area, notably EE endpoints. This creates friction for customers and AI agents trying to discover and adopt GitLab's full API capabilities, and makes it difficult for external teams to programmatically generate client libraries, tools, and integrations. By completing the OpenAPI 3.0 specification to cover the entire API surface area (including EE) and deploying interactive documentation using Scalar, the API Platform team will enable: - **Customers & AI Agents**: Interactive, complete API reference (via Scalar) that eliminates discovery friction. Customers and agents can explore the full REST API surface, including EE, without digging through incomplete Markdown docs. - **Ecosystem & Integrations**: Machine-readable OpenAPI 3.0 spec enables automatic SDK generation, reducing the engineering effort required for third-party integrations and lowering the barrier for partners and customers to build on GitLab. - **API-First Development**: A single authoritative spec becomes the contract across teams, unlocking schema validation in CI, spec-driven design reviews, and a foundation for consistent API governance as the surface area grows. ## Exit criteria - [x] Evaluate options for serving the interactive documentation. Decide on the best tool to use - [x] Buy, configure, or set up our chosen tool - [x] Integrate the OpenAPI spec - [x] Update any required documentation or onboarding issues to help people discover (if needed) - [x] Document any ongoing maintenance work needed <!-- STATUS NOTE START --> ## Status 2026-03-12 :clock1: **total hours spent this week by all contributors**: 4 :tada: **achievements**: - Project complete **Closing Status** **Original Problem**: GitLab's REST API documentation was limited to manually maintained Markdown covering only a subset of the API. The incomplete OpenAPI 2.0 spec lacked EE endpoints and ability for interactivity, creating friction for customers, AI agents, and external teams trying to discover and build on GitLab's full API capabilities. **Changes Made**: - Generated a [valid OpenAPI 3.0](https://gitlab.com/groups/gitlab-org/quality/-/work_items/218) specification covering the entire REST API surface area, including EE endpoints - Deployed an experimental API reference using open source tooling [Scalar](https://github.com/scalar/scalar) - Established the [API Docs](https://gitlab.com/gitlab-com/gl-infra/api-docs) project for foundation **Impact**: The full GitLab REST API is now discoverable and explorable through an experimental interactive reference for the first time. A complete, machine-readable OpenAPI 3.0 spec will unlock the ability to render API lifecycle status on all endpoints using end-to-end automation. This experimental deployment validated adoption of OpenAPI and Scalar tooling for automated solution and provides the foundation for iterating on https://gitlab.com/groups/gitlab-org/quality/-/work_items/369+, which will continue next steps to complete branding styles, performance optimizations, and public launch preparation/comms. **Demo**: https://api-docs-a0ae81.gitlab.io Shout-out to `@mwoolf`, `@abignotti`, `@idurham`, `@kkloss` for their collaboration on this foundational work 🚀 --- **Please close this epic in the next Platforms Grand Review.** _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/261#note_3152601388_ <!-- STATUS NOTE END -->