Skip to content

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

Open
rubenvdlinde wants to merge 2 commits into
developmentfrom
quality/build-governance-rest-api-reference-c2
Open

rubenvdlinde wants to merge 2 commits into
developmentfrom
quality/build-governance-rest-api-reference-c2

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

Continues the build of openspec/changes/governance-rest-api-reference (the stability markers and their pinning test landed in #1202).

Tasks done

  • 5 docs/features/rest-api.md: where the reference lives (openapi.json, also served at /api/v1/openapi.json), the base URL, Basic authentication with a Nextcloud app password plus OCS-APIRequest: true, what public and internal mean, and which operations are public.
  • 4, route half: composer lint:openapi (scripts/lint-openapi.php, logic in scripts/OpenApiRouteCoverage.php) added to check:strict. It fails on a versioned API route with no operation, an operation without x-launchpad-stability, or an operation without a route. Path parameters are compared by position; the catch-all API fallback is skipped.
  • The new check found GET/PUT /analytics/me without a stability marker (the cause of the OpenApiStabilityTest failure on development). Both are marked internal; the pinned public set is unchanged.

Tasks left, and why

  • 1 Try nextcloud/openapi-extractor and record the generator choice (D1). Adding the dev dependency and judging its output against the existing 184-operation document needs a person.
  • 2, 3 Response shape annotations and generating openapi.json both depend on that choice.
  • 4, regenerate-and-compare half: needs the generator from 1/3. Left unticked until then.
  • 6 Archive and parity row: release task.

Tests

  • tests/Unit/Scripts/OpenApiRouteCoverageTest.php (6): matching routes pass whatever the parameter names; a fixture with an undocumented route fails and names it; a missing or unknown stability fails; an operation without a route fails; the fallback route is skipped; the committed document covers the app's routes. Disabling the undocumented-route check turns it red.
  • PHPUnit: development 4136 tests, 1 failure (OpenApiStabilityTest, /analytics/me); this branch 4142 tests, 0 failures.
  • composer lint:openapi: 184 operations, every API route documented. phpstan clean on the new class.
  • Docs: docusaurus build succeeds and builds docs/features/rest-api. Its only warnings come from the docs preset and are not new.

Generated by Claude Code

Task 5: the REST API page in the docs, with Basic authentication by app
password and the OCS-APIRequest header, and what public and internal
stability mean.

Task 4 (route half of the drift check): composer lint:openapi, in
check:strict, fails on an API route without an operation, an operation
without x-launchpad-stability, or an operation without a route. It
found GET and PUT /analytics/me unmarked; both are now internal, which
also turns OpenApiStabilityTest green again.

Assisted-by: ClaudeCode:claude-opus-5-5
Assisted-by: ClaudeCode:claude-opus-5-5
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