The shared source of truth is docs/api-spec.openapi.yaml. Do not treat frontend/docs/openapi/public-api.openapi.yaml as the file to edit directly. That file exists so Mintlify can render the reference.

​
Update workflow

  1. Change docs/api-spec.openapi.yaml.
  2. Run npm run sync:openapi from frontend/docs.
  3. Run npm run validate:openapi or npm run validate to validate the Mintlify docs build with the mirrored spec.
  4. Preview with npm run dev.
  5. Commit the shared spec and the mirrored file together.

​
What should trigger an OpenAPI update

  • adding or removing a route
  • changing a request or response field
  • changing auth requirements
  • changing error codes or messages that clients rely on
  • changing server URLs used in docs or the playground

​
Starter rule

If the backend contract changed and the shared OpenAPI file did not, the docs change is incomplete.

​
Why this is manual on purpose

This repo does not use swagger annotations or automatic OpenAPI generation today. The starter keeps the maintenance path explicit so teams can adopt docs immediately without reworking the HTTP stack first. If the repo later adopts code generation, this page is where that workflow should be updated.