Skip to content

feat(launchpad): build governance-rest-api-reference - #1202

Merged
rubenvdlinde merged 1 commit into
developmentfrom
quality/build-governance-rest-api-reference
Nov 14, 2026
Merged

rubenvdlinde merged 1 commit into
developmentfrom
quality/build-governance-rest-api-reference

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

Builds part of openspec/changes/governance-rest-api-reference: the stability levels of design D2. No task is ticked, because each touched task has a part that is not done (see below).

What this does

  • Every one of the 182 operations in openapi.json now carries x-launchpad-stability.
  • 24 are public, as D2 lists them:
    • dashboard CRUD and listing (/dashboard, /dashboard/{id}, /dashboards, /dashboards/visible);
    • placements and tiles (/dashboard/{dashboardId}/widgets, /widgets/{placementId}, /dashboard/{dashboardId}/tile, /tiles, /tiles/{id});
    • sharing (/dashboard/{id}/shares, /dashboard/share/{shareId});
    • public links (/dashboards/{uuid}/public-share(s));
    • export and import (/admin/export, /admin/import).
  • Every other operation is internal.
  • OpenApiStabilityTest fails when an operation has no stability, or when the public set changes without editing the pinned list in the test.

Tasks left, and why

  • 1 Try nextcloud/openapi-extractor / 3 generate the file as OpenAPI 3.1. Since this change was written, openapi.json (3.0.3) landed on development in feat(api): serve every API path under /api/v1…. It is drawn from routes.php and the controllers, and OpenApiDocumentTest keeps it in step with the routes both ways. Whether to replace it with a generator is the D1 decision. That needs a person, so it is not made here, and the stability markers were added to the existing file.
  • 2 Response and request shape annotations on the public controllers: not done.
  • 4 composer lint:openapi in check:strict: the route-coverage half already exists as OpenApiDocumentTest. The regenerate-and-compare half depends on 1.
  • 5 Docusaurus API page, 6 archive fold and parity row: not done.

Tests

  • OpenApiStabilityTest (1 test, 183 assertions).
  • PHPUnit: 4069 tests, OK (13 skipped, as on development).

Generated by Claude Code

Mark every operation of openapi.json x-launchpad-stability public or
internal (design D2): dashboard CRUD and listing, placements and tiles,
sharing, public links, export and import are public, the rest internal.
A test pins the public set, so moving an operation in or out of it is a
deliberate edit.

Assisted-by: ClaudeCode:claude-opus-5-5
rubenvdlinde added a commit that referenced this pull request Nov 14, 2026
GET and PUT /admin/public-start are admin settings, not part of the public
API, so they carry x-launchpad-stability: internal as the operation
stability check (arriving with #1202) requires of every operation.

Assisted-by: ClaudeCode:claude-opus-5-5
@rubenvdlinde
rubenvdlinde merged commit 79cc97b into development Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant