HTTP API reference

The Food Truck Nerdz Next.js app exposes JSON HTTP endpoints for authentication, multi-tenant business access (memberships and roles), and Square-backed menu operations. This page publishes a machine-readable OpenAPI 3 document alongside the rest of the Antora docs so integrators (and tooling) can rely on one canonical description.

OpenAPI specification

The spec is written for humans first: info.description, tags, and schema property descriptions explain why fields exist and how tenants relate to users— not only field types.

  • Canonical file in this repo: docs/modules/ROOT/attachments/openapi/ftn-public-api.yaml

  • Published with the docs site: ftn-public-api.yaml (Antora attachment; URL depends on your playbook and host)

Because the source repository is private, a bookmarkable https://editor.swagger.io/?url=... link to a public spec is not viable without exposing the file. Use the in-site explorer below (once the playbook enables it) or the DIY Swagger Editor steps.

Interactive API explorer (Swagger UI)

The block below embeds Swagger UI on this page. It requires the Antora extension @opendevise/antora-swagger-ui-extension in the docs-site playbook project (Node 18+, Antora 3.1+).

Playbook (antora-playbook.yml or equivalent)
antora:
  extensions:
  - '@opendevise/antora-swagger-ui-extension'

In the playbook project: npm i @opendevise/antora-swagger-ui-extension (or add the dependency there). The extension injects Swagger UI assets into the Antora UI when this macro is used.

swagger-ui::attachment$openapi/ftn-public-api.yaml[docExpansion=list]

If the site build fails with an unknown swagger-ui macro, register the extension in the playbook first, then rebuild.

DIY: Swagger Editor (hosted demo)

For ad-hoc validation or sharing screenshots, use Swagger Editor without a bookmarkable ?url= to a private spec (that pattern needs a public spec URL and permissive CORS).

  1. Obtain the YAML: clone this repo and open docs/modules/ROOT/attachments/openapi/ftn-public-api.yaml, or download the attachment from your authenticated docs site after publish.

  2. In Swagger Editor: menu:File[Import File] and choose the file (or drag the file into the window).

No second “publication” step beyond your normal docs deploy; the spec file in git is the source of truth.

Other viewers

  • Redoc / CLI — good for long narrative descriptions; same file as above.

  • IDE plugins — many editors render OpenAPI from the same YAML.

Authentication quick reference

  • Browsers: Better Auth session cookie after OAuth or email sign-in.

  • Mobile / API clients: After POST /api/auth/sign-in/email (or sign-up), read the set-auth-token response header and send Authorization: Bearer <token> on later requests (Better Auth bearer plugin).

  • Tenant: Data is keyed by the business owner’s Convex user id (businessOwnerUserId). Staff and managers use memberships to act on that tenant; see the spec’s introduction for full detail.

Keeping the spec honest

When you change any of the following, update ftn-public-api.yaml in the same change (or immediately after) so docs and code do not diverge:

  • GET /api/auth/me or related Convex auth context types

  • Better Auth–related assumptions (bearer header name, cookie vs token)

  • Square or menu routes under /api/getSquareItems, /api/square/*, /api/auth/disconnect

For exhaustive Better Auth paths not duplicated here, use the Better Auth documentation.