OpenAPI

The rendered reference is the API site. npm run build and npm start run scripts/prepare-openapi.mjs first.

static/openapi/openapi.yaml is a snapshot of splick-backend/openapi/openapi.yaml. It is not edited by hand. The snapshot currently contains $ref pointers that do not resolve (missing response components and several schemas). The prepare script rewrites only those pointers to #/components/schemas/UnresolvedRef so Redoc can render the rest of the contract. The rewritten file is static/openapi/openapi.site.yaml and is gitignored. Fix the pointers in the backend spec and the placeholder disappears on the next sync.

cd splick-docs
npm run sync-openapi

The script copies ../splick-backend/openapi/openapi.yaml when you run it from a monorepo checkout. Pass another path as the first argument if the backend lives elsewhere.

Commit the snapshot in the same docs change as the prose that describes the new route. CI builds the site with onBrokenLinks: throw. It does not diff the snapshot against the backend. The reviewer does.

Backend validation stays make -C splick-backend openapi-validate. Postman sync stays in the backend repo (docs/postman-sync.md).