​
Layout

  • frontend/docs contains the Mintlify site
  • docs/api-spec.openapi.yaml is the shared OpenAPI source of truth
  • frontend/docs/openapi/public-api.openapi.yaml is the mirrored file Mintlify reads

​
Why the OpenAPI file is mirrored

Mintlify expects repository-local OpenAPI files for generated API pages. This starter keeps the actual source of truth in the repo-level docs/ folder so it can be reviewed alongside backend changes and reused outside the docs app. The docs app mirrors that file through frontend/docs/scripts/sync-openapi.mjs. That gives you a workable split:
  • edit the shared source in docs/api-spec.openapi.yaml
  • sync it into the docs app before previewing or committing docs changes
  • let Mintlify render the mirrored file

​
Initial API surface

The starter spec is deliberately small and covers only public-api:
  • GET /health
  • GET /ready
  • GET /v1/meta
  • GET /v1/public/token-info
  • GET /v1/public/tenant-info
That keeps the starter easy to understand while still demonstrating:
  • shared health and metadata routes
  • bearer-token auth
  • success/error response envelopes
  • multi-tenant public ID payloads

​
Backend files that anchor the spec

  • backend/cmd/public-api/main.go for route behavior and payload fields
  • backend/internal/apiserver/router.go for shared service routes
  • backend/internal/platform/respond.go for the standard response envelope
  • backend/internal/auth/api_token_middleware.go for bearer-token auth and failure modes
Use those files when the shared spec needs to be updated.