endpoints

(no submodules)

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

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

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

2.4 KiB Raw Blame History