mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 04:32:42 +00:00
Marc-André BombeckandClaude Opus 4.7
75b52b1f30
Generates `docs/api/openapi.yaml` covering the full REST surface — 100+ paths across 24 tags, 130+ schemas under `components.schemas`. Two security schemes: `sessionCookie` (HttpOnly `healthlog_session`) plus `bearerAuth` (HTTP Bearer for the API tokens at `/api/tokens`). Admin routes are explicitly tagged + restricted to `sessionCookie`. `docs/api/README.md` documents how to preview the spec locally (`npx @redocly/cli preview docs/api/openapi.yaml`) and lists the few known lint warnings (localhost server, redirect endpoints without 2xx). Lint pass: 0 errors, 17 warnings (none introduced by this commit). Spec is hand-maintained for now; a future commit can wire it into a `pnpm openapi:lint` CI step. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# HealthLog API Spec
|
|
|
|
`openapi.yaml` is the canonical OpenAPI 3.1 description for the HealthLog
|
|
Next.js API. It is the source of truth for the native iOS client's
|
|
DTO codegen.
|
|
|
|
## Preview locally
|
|
|
|
Open an interactive Redoc preview in your browser:
|
|
|
|
```bash
|
|
npx @redocly/cli preview docs/api/openapi.yaml
|
|
```
|
|
|
|
Generate static HTML for sharing:
|
|
|
|
```bash
|
|
npx @redocly/cli build-docs docs/api/openapi.yaml --output docs/api/index.html
|
|
```
|
|
|
|
## Validate
|
|
|
|
```bash
|
|
npx @redocly/cli lint docs/api/openapi.yaml
|
|
```
|
|
|
|
The spec is expected to be lint-clean (errors = 0). Some warnings are
|
|
intentional:
|
|
|
|
- `no-server-example.com` — `http://localhost:3000` is the dev server.
|
|
- `operation-2xx-response` / `operation-4xx-response` — webhook + redirect
|
|
endpoints intentionally omit one or the other.
|
|
- `no-unused-components` — `ReminderPhase` is exposed for client codegen
|
|
even though no path response references it directly.
|
|
|
|
## Layout
|
|
|
|
- **`info`** — title, version (mirrored from `package.json`), description.
|
|
- **`servers`** — production `https://healthlog.bombeck.io` plus
|
|
`http://localhost:3000` for local development.
|
|
- **`tags`** — domain groupings (`Auth`, `Measurements`, `Medications`,
|
|
`Mood`, `Dashboard`, `Insights`, `Achievements`, `DoctorReport`,
|
|
`Integrations`, `User`, `Tokens`, `Notifications`, `Onboarding`,
|
|
`Health`, `Settings`, `Analytics`, `Export`, `AuditLog`, `Feedback`,
|
|
`BugReport`, `Monitoring`, `Webhooks`, `Ingest`, `Admin`).
|
|
- **`securitySchemes`**:
|
|
- `bearerAuth` — long-lived `hlk_*` API tokens issued via `POST /api/tokens`.
|
|
Required on `/api/ingest/medication`.
|
|
- `sessionCookie` — HttpOnly `healthlog_session` cookie set by the
|
|
password and passkey login flows. Used by the web app and any iOS
|
|
client running inside a web view.
|
|
- **`components.schemas`** — DTOs for all routes plus the underlying
|
|
Prisma models (e.g. `Measurement`, `Medication`, `MedicationIntakeEvent`,
|
|
`MoodEntry`, `User`, `DashboardLayout`, `ApiEnvelope`, `ApiError`).
|
|
- **`paths`** — all routes from `src/app/api/**/route.ts`, including
|
|
the `/api/admin/*` family which is tagged `Admin` and marked internal.
|
|
|
|
## Conventions
|
|
|
|
- Successful responses use the envelope `{ data, error: null }`.
|
|
- Error responses use the envelope `{ data: null, error: '<message>' }`.
|
|
- Pagination uses `limit` + `offset` query parameters and a
|
|
`meta: { total, limit, offset }` block on the response.
|
|
- All timestamps are ISO 8601 / RFC 3339 (`format: date-time`) in UTC.
|
|
- IDs are CUIDs (opaque strings).
|
|
|
|
## Updating the spec
|
|
|
|
When adding or changing routes:
|
|
|
|
1. Update the relevant route handler under `src/app/api/**/route.ts`.
|
|
2. Mirror the change in `openapi.yaml`. Keep `operationId` camelCase and
|
|
stable — the iOS codegen keys off it.
|
|
3. Run `npx @redocly/cli lint docs/api/openapi.yaml` and resolve all
|
|
errors. Warnings are tolerated when documented above.
|
|
4. Bump `info.version` if the change is breaking for clients.
|