docs(openapi): add management API v1 contract and CI validation

What

Adds the hand-authored OpenAPI 3.1 contract for the management API's hosted repository CRUD endpoints, ahead of the Go handlers, plus the tooling to validate, render, and publish it.

  • api/openapi/v1.yaml: the five repository operations (list, create, get, update, delete), the resource and request schemas, the format/kind/visibility enums, the bearer security scheme, and each success and failure response.
  • api/openapi/redocly.yaml: lint config whose struct rule validates the document against the OpenAPI 3.1 meta-schema, plus the apis entry used by the local preview.
  • .gitlab-ci.yml: the lint:openapi validate-stage job (runs on api/openapi/ changes; an invalid document fails the pipeline), and the pages job extended to render the contract (see below).
  • .mise.toml: the api:preview task and the @redocly/cli tool pin.
  • .gitlab-ci-other-versions.yml: pin @redocly/cli, Renovate-tracked.
  • docs/dev/api-style.md: document the contract location, the CI gate, the (planned) kin-openapi handler check, local preview, and the published reference.

Rendered HTML docs

The contract is rendered to a browsable HTML reference with Redoc:

  • Published: the pages job renders it to static HTML and publishes it to GitLab Pages at /api/, on the default branch. The database ERD moves to /erd/ and a landing page at the site root links both.
  • Local preview: mise run api:preview serves a live-reloading Redoc preview at http://localhost:4000.

Plan

Step 1 of the S17 Phase 1 hosted repository CRUD plan (docs/plans/2026-06-22-s17-phase1-repository-crud.md).

Testing

redocly lint validates the contract against the 3.1 meta-schema (the new lint:openapi job); a deliberately malformed document fails it. redocly build-docs and mise run api:preview both render it cleanly. No Go tests: the kin-openapi response contract checks land with the handler steps.

Related to #171 (closed)

Edited by João Pereira

Merge request reports

Loading
Loading