first commit

docs/api-stack/api/api-openapi/src/endpoints/endpoints.md

@@ -0,0 +1,71 @@
+# endpoints
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`endpoints` mounts the four HTTP routes the design doc reserves for the
+OpenAPI surface — `/openapi.json`, `/openapi.yaml`, `/docs`, and
+`/docs/:plugin` — onto a Hono app. The handlers are minimal: they read
+the memoised emitter, set the appropriate `Content-Type`, and return
+the body. UI sibling packages (Scalar, Swagger, ReDoc) replace the
+default HTML stubs with their renderers.
+
+Separating endpoints from the emitter keeps the host wiring simple: the
+host builds an emitter once at boot, then mounts the router at whatever
+path it prefers (commonly `/`).
+
+## Features
+
+- `createOpenapiRouter({ emitter })` — standalone Hono router with the
+  four routes wired.
+- `mountOpenapiEndpoints(app, { emitter })` — convenience that attaches
+  the router onto an existing Hono app.
+- 404 + typed body for unknown plugins via the filtered view (the
+  emitter raises `OPENAPI.UNKNOWN_PLUGIN_IN_FILTER` and the handler
+  catches it).
+- Content negotiation: JSON, YAML, HTML — each handler sets its
+  `Content-Type` explicitly.
+
+## Usage: Basic
+
+```ts
+import { Hono } from "hono";
+import { mountOpenapiEndpoints } from "@suaveplan/api-openapi/endpoints";
+
+const app = new Hono();
+mountOpenapiEndpoints(app, { emitter });
+// app now serves GET /openapi.json, /openapi.yaml, /docs, /docs/:plugin
+```
+
+## Usage: Advanced
+
+```ts
+import { Hono } from "hono";
+import { createOpenapiRouter } from "@suaveplan/api-openapi/endpoints";
+
+const root = new Hono();
+const docs = createOpenapiRouter({ emitter });
+root.route("/admin/api", docs);
+// Routes mount at /admin/api/openapi.json, etc.
+```
+
+## API Reference
+
+- `createOpenapiRouter(options) → Hono`.
+- `mountOpenapiEndpoints(app, options) → app` — returns the passed app.
+- `OpenapiEndpointsOptions = { emitter: OpenapiEmitter }`.
+
+## Implementation Notes
+
+- The HTML stubs are bare on purpose. UI sibling packages
+  (`@suaveplan/api-openapi-ui-scalar`, etc.) own the docs experience;
+  this package only ships the data-bearing endpoints.
+- Body returns: `c.body()` is used (not `c.json()` / `c.text()`) so the
+  serialised string the emitter already produces is forwarded verbatim
+  — no double-stringify for JSON, no JSON-encoding of YAML.
+- The unknown-plugin 404 returns the OpenAPI error code in the body so
+  clients can disambiguate from "this plugin exists but has no routes"
+  scenarios (where the filtered view returns an empty `paths` object).