[product-pages] Ship static/oas/procest.json OpenAPI spec for Redocusaurus

[rubenvdlinde]

Source: AUDIT-product-pages-2026-05-13.md fleet audit · canonical reference: openregister docusaurus.config.js redocusaurus block

The migration PR adds redocusaurus to package.json and configures the /api route in docusaurus.config.js, pointing at static/oas/{app}.json. This issue tracks shipping a real OpenAPI spec to populate it.

Scope

• Extract or hand-author an OpenAPI 3.1 (or 3.0) spec for the app's REST surface.
• Drop into docs/static/oas/{app}.json.
• Cover the routes a third party would actually call (read/write objects, search, key admin endpoints).
• Include request / response schemas, auth scheme (Bearer token via Nextcloud session or OAuth where applicable).

Approach options (pick one)

1. Generate from PHP controllers — Nextcloud OCS routes have docblocks; tooling like nelmio/api-doc-bundle or hand-rolling a generator works for OCA apps. Best long-term.
2. Hand-author the JSON — fast for an MVP spec, brittle to maintain.
3. Import from existing source — if the app already has a partial spec elsewhere (issues, PRs, wiki), normalize and ship it.

Acceptance

• docs/static/oas/{app}.json validates against the OpenAPI 3.x schema (use swagger-cli validate or redocly lint).
• Visiting https://{app}.conduction.nl/api in a browser shows the Redoc three-pane layout (endpoint list left, doc middle, request samples right).
• At least the object CRUD + search endpoints are documented with full request/response.