OpenAPI

A machine-readable OpenAPI 3.1 spec is served from the API Worker itself. It is generated from the route definitions in apps/api/src/routes/*.ts, so it's always in sync with what's actually deployed.

Where to get it

What's in the spec

• Every public, owner, and customer endpoint
• Path parameters, query parameters, request bodies
• Response shapes (200, 4xx, 5xx)
• Authentication (Bearer JWT)
• Rate limit headers
• Error response shapes

Importing into Postman

1. Open Postman, click "Import"
2. Paste the URL https://booking-api.netwit.ca/api/openapi.yaml
3. Postman generates a collection with one request per endpoint
4. Set the baseUrl variable to your environment (prod or localhost)
5. Set the token variable from POST /api/auth/login

Importing into Insomnia

1. Click "Create" → "Import from URL"
2. Paste the OpenAPI URL
3. Insomnia creates a request collection
4. Set environment variables for baseUrl and token

Generating a client

Use openapi-generator to produce a typed client in your language of choice:

npx @openapitools/openapi-generator-cli generate \
  -i https://booking-api.netwit.ca/api/openapi.yaml \
  -g typescript-fetch \
  -o ./bookflow-client \
  --additional-properties=supportsES6=true

Other supported generators include: typescript-node, python, go, java, kotlin, swift, ruby, php, csharp.

Verifying the spec

Once the spec ships, it will be validated at deploy time by a CI check against the route definitions.