# 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).