Migrate API documentation away from apiDoc to an OpenAPI-based solution #416

Background

The project currently generates its API reference with apidoc@0.29.0, using @api* comments in PHP controllers and shared definitions in app/Docs / ItemController. The documentation is built by scripts/build-pages.cjs with the custom resources/template-apidoc template and published to GitHub Pages.

Upgrading to apiDoc 1.x is not a drop-in change: #414 introduces an esbuild install-script approval failure in CI, and the new apiDoc template/build pipeline is incompatible with the existing custom template.

Rather than investing in the legacy generator and template, evaluate moving to a modern, preferably OpenAPI-based documentation workflow.

Goals

• Adopt a maintainable, machine-readable API specification (preferably OpenAPI), alongside a usable, publicly accessible API reference.
• Generate and publish documentation statically in CI (GitHub Pages), without requiring a running Cattr instance for visitors.
• Keep the API documentation aligned with actual Laravel routes, validation and responses, including authentication, permissions, errors and request/response examples.
• Retain useful existing @api* descriptions and shared definitions during migration; do not silently lose coverage or details.
• Avoid introducing documentation tooling or generation routes into the production application unless there is a clear reason.

Tooling to evaluate — proposals, not a decision

Potential approaches include:

• Scribe + Scalar: Laravel-oriented extraction and enrichment, OpenAPI output and static publishing.
• Scramble + Scalar: route/type-based OpenAPI generation with a separately rendered static reference.
• Other suitable OpenAPI generators and renderers (e.g. Swagger UI or Redoc) should remain in scope.

No generator, renderer, OpenAPI version or implementation strategy is selected by this issue. Evaluate suitability, ongoing maintenance, output quality, framework compatibility, build/dependency impact and required manual work. Document the choice and rationale before implementation.

Migration considerations

• Existing documentation is split across controller annotations and common @apiDefine / @apiUse blocks.
• API routes include Route::any(), nonstandard/legacy endpoints and deprecated operations; compare generated operations with the effective Laravel route table, not merely existing comments.
• FormRequest validation and responses built via flugger/laravel-responder may not be inferred accurately by automatic generators.
• Cover bearer-token authentication, access restrictions, non-JSON/file responses (including screenshot upload and report downloads), and shared error schemas.
• Preserve the existing public documentation URL where practical or provide appropriate redirects; avoid enabling unauthenticated production Try it out access by default.
• Treat API compatibility/version information and module-provided routes explicitly.

Suggested work plan

• Audit current API documentation, actual Laravel routes and coverage gaps.
• Prototype at least two candidate approaches using representative endpoints (auth, task list, time interval creation, file upload/download, errors).
• Record the tooling decision and its trade-offs before committing to an implementation.
• Migrate descriptions, examples, shared request/response schemas, authentication and deprecated endpoints.
• Integrate specification generation, validation and static documentation publishing into CI/GitHub Pages.
• Verify output against the route table and representative real responses, and smoke-test the published UI.
• Remove apiDoc, its custom template and obsolete build logic only after feature/coverage parity is established.

Acceptance criteria

• The chosen approach and rationale are documented; tool choices in this issue are not assumed to be mandatory.
• A reproducible CI build generates a valid API specification and static documentation without contacting a live production server.
• Supported API operations, auth, parameters, responses and error models are documented; any intentional exclusions are listed.
• The rendered API reference works on GitHub Pages with existing links preserved or redirected.
• Old apiDoc-specific dependencies/templates are removed after successful migration, with no regression to application/frontend CI.

Related: #414.