Loading
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, theformat/kind/visibilityenums, the bearer security scheme, and each success and failure response.api/openapi/redocly.yaml: lint config whosestructrule validates the document against the OpenAPI 3.1 meta-schema, plus theapisentry used by the local preview..gitlab-ci.yml: thelint:openapivalidate-stage job (runs onapi/openapi/changes; an invalid document fails the pipeline), and thepagesjob extended to render the contract (see below)..mise.toml: theapi:previewtask and the@redocly/clitool 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-openapihandler check, local preview, and the published reference.
Rendered HTML docs
The contract is rendered to a browsable HTML reference with Redoc:
- Published: the
pagesjob 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:previewserves a live-reloading Redoc preview athttp://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