mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
de33f1ad4c
Drop the in-app bug-report surface end to end: the user submission page, the feedback intake and admin inbox, the optional GitHub-issue escalation, the operator config, and the dedicated achievement badges. - delete the /bugreport page and the bugreport / feedback / admin-feedback API routes - drop the Feedback model, its enums, and the AppSettings GitHub-issue and enable columns (migration 0205) - remove the admin Feedback section, the Bug Report integration card, and the system-status row - drop the bug-report nav entry and the app-settings provider that only carried its flag - remove the bug-hunter achievement badges and their metric - prune the related i18n keys across every locale and the encrypted-column and key-rotation registries
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`,
|
|
`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.
|