Add endpoint-level OpenAPI coverage

Author: cuteshaun

.github/workflows/ci.yml

@@ -54,13 +54,13 @@ jobs:
         run: pnpm test
 
       - name: OpenAPI drift gate
-        # Regenerates the stub from the Zod schemas and fails if it
-        # differs from the committed artefact at
-        # `docs/openapi.stub.json`. Forces every DTO change to land
-        # together with its spec update.
+        # Regenerates the spec from the Zod schemas and route
+        # definitions and fails if it differs from the committed
+        # artefact at `docs/openapi.json`. Forces every DTO or route
+        # change to land together with its spec update.
         run: |
           pnpm openapi
-          git diff --exit-code docs/openapi.stub.json
+          git diff --exit-code docs/openapi.json
 
       - name: Next.js build
         run: pnpm build

apps/docs/src/content/docs/openapi.mdx

@@ -3,8 +3,10 @@ title: OpenAPI Spec
 description: Machine-readable OpenAPI schema for the API
 ---
 
-The full OpenAPI schema describes every endpoint, parameter, and response shape. Use it with code generators, Swagger/Redoc viewers, or Postman.
+The OpenAPI 3.0.3 document describes every endpoint with its parameters, response envelopes, and error shape. Use it with code generators, Swagger/Redoc viewers, or Postman.
 
 ```
 https://l2api.dev/api/openapi.json
 ```
+
+List rows, drops, shops, hennas, and meta endpoints carry exact schemas. The large detail responses (item, NPC, quest, class, armor set, raw NPC) currently document their stable top-level fields and allow additional properties — full field-level precision for those is planned. The prose contract in the repo's `docs/api-contract.md` remains the authoritative field reference.

docs/api-contract.md

@@ -784,24 +784,35 @@ to do in one shot and is being staged in three phases.
 compile-time
 `Expect<Equals<z.infer<typeof Schema>, ExistingDto>>` assertion, so
 any drift between the schema and the hand-written interface fails
-`pnpm typecheck`. A stub OpenAPI document
-(`docs/openapi.stub.json`) is regenerated by `pnpm openapi`. The
-schemas file is **not imported by route handlers**, so Zod stays
-out of the runtime lambda bundle. Public response shapes are
-unchanged by Phase A — schemas are an additive type-system safety
-net, not a runtime validator.
+`pnpm typecheck`. The OpenAPI document (`docs/openapi.json`) is
+regenerated by `pnpm openapi`. The schemas file is **not imported
+by route handlers**, so Zod stays out of the runtime lambda bundle.
+Public response shapes are unchanged by Phase A — schemas are an
+additive type-system safety net, not a runtime validator.
+
+**Endpoint-level path coverage (landed)** —
+`scripts/audit/generate-openapi.ts` registers every public route
+under `src/app/api/[chronicle]/` with its path/query parameters,
+the `{ data }` / `{ data, meta }` envelopes, and the shared
+`{ error, status }` error schema. List/summary, drop, item-source,
+shop, meta-count, raw-spawn, and henna-detail schemas are **exact**
+and carry the same compile-time `Equals` assertions (checked by
+`pnpm typecheck:scripts`). The large detail schemas (`ItemDetail`,
+`NpcDetail`, `QuestDetail`, `ClassDetail`, `ArmorSet`, `RawNpc`)
+are **approximate**: they document the stable top-level fields and
+set `additionalProperties: true` pending Phase B.
 
 **Phase B (deferred)** — migrate the larger DTOs (`ItemDetailDto`,
 `NpcDetailDto`, `QuestDetailDto`, etc.) one at a time and switch
 their TypeScript types to `z.infer<typeof ...>`, making schemas the
 source of truth. Each migration must pass the existing snapshot
 suite without diff. Routes still don't validate at runtime.
 
-**Phase C (deferred)** — register every route's request/response in
-the OpenAPI registry and generate a complete spec. The Phase-A stub
-is already published at runtime via `GET /api/openapi.json`, so
-Phase C is purely about widening `components.schemas` and populating
-`paths` — not about distribution.
+**Phase C (deferred)** — replace the approximate detail schemas in
+the spec with the exact Phase-B schemas. The document is already
+published at runtime via `GET /api/openapi.json` with full path
+coverage, so Phase C is purely a precision pass on
+`components.schemas` — not about distribution.
 
 The roadmap is intentionally conservative: snapshots remain the
 authoritative regression detector through all three phases. A bug
@@ -856,4 +867,4 @@ and should not be pinned by external consumers:
 
 - [`api.md`](./api.md) — external-facing API overview (endpoints, query params, examples).
 - [`AGENTS.md`](../AGENTS.md) — project-wide engineering principles, scope, and out-of-scope notes.
-- [`openapi.stub.json`](./openapi.stub.json) — auto-generated stub spec covering the Phase-A schemas. Regenerate with `pnpm openapi`.
+- [`openapi.json`](./openapi.json) — auto-generated OpenAPI 3.0.3 spec covering every public route; detail-DTO schemas are approximate pending Phase B. Regenerate with `pnpm openapi`.

docs/api.md

@@ -133,7 +133,7 @@ The same `HennaSummary` shape appears as a cross-link from item detail (`ItemDet
 
 | Method | Path | Description |
 |---|---|---|
-| GET | `/api/openapi.json` | OpenAPI 3.0 document for the API. Chronicle-agnostic — the document describes `/api/{chronicle}/...` as a parameterised path, with `{chronicle}` exposed as a server-template variable. Phase A: `components.schemas` is populated for the small reusable cross-link DTOs (`NpcRef`, `ClassRef`, `QuestRef`, `RegionRef`, `LocationRef`, `EnrichedSpawn`, `QuestClientJournalEntry`, `HennaSummary`); `paths` is intentionally empty pending Phase C per-route generation (see `docs/api-contract.md`). The document is the committed `docs/openapi.stub.json` build artifact, served as a convenience without an envelope. |
+| GET | `/api/openapi.json` | OpenAPI 3.0.3 document for the API. Chronicle-agnostic — every data path carries an explicit `{chronicle}` path parameter against the `/api` server root. `paths` covers every public route with its parameters and response envelopes; list/summary, drop, shop, meta, and henna schemas are exact, while the large detail schemas (`ItemDetail`, `NpcDetail`, `QuestDetail`, `ClassDetail`, `ArmorSet`, `RawNpc`) document stable top-level fields and allow additional properties pending the Phase B Zod migration (see `docs/api-contract.md`). The document is the committed `docs/openapi.json` build artifact, served as a convenience without an envelope. |
 
 ## Response shapes