@tetsujs/openapi

@tetsujs/openapi reads an application’s routes and produces an OpenAPI 3.1 document and a page that renders it. Paths, parameters, bodies and responses come from the schemas and response maps the routes already have, so nothing is written twice. To turn the document into a typed client, see Typed client from OpenAPI.

bun add @tetsujs/openapi

Usage

Mount the docs() controller next to your own:

import { docs } from "@tetsujs/openapi";

createApp({
  routes: [
    group("/api", { children: [usersController()] }),
    docs({ info: { title: "Users API", version: "1.0.0" } }),
  ],
});

/openapi.json serves the document and /docs renders it. The document covers the whole application docs() is mounted in, except its own two routes. It is built once, at startup, so anything that cannot be described is reported before the first request.

docs() is an ordinary controller: put it in a group to move it under a prefix, guard it with hooks, or leave it out in production. A group does not narrow the document, so two documents, such as a public API and an admin one, need two applications, each with its own docs().

A route adds what the schemas cannot say in docs:

const list = route({
  method: "GET",
  path: "/users",
  docs: { summary: "List users", tags: ["users"], operationId: "listUsers" },
  handler: () => [],
});

docs also takes description, deprecated, and hidden: true, which leaves the route out of the document while it is still served. hidden: false keeps a route in when its handler would hide it, see Documenting a handler. WebSocket endpoints are never in the document: OpenAPI cannot describe what happens after the handshake.

Options

Option	Default
info	required	the document’s info: title, version, description
servers	none	where the API is reachable
path	/openapi.json	where the document is served
uiPath	/docs	where the page is served
ui	"scalar"	"scalar", "swagger-ui", "redoc", or false for no page
title	the document’s title	the page’s title
assets	the renderer on jsDelivr, pinned	your own renderer URLs, with integrity hashes, see The page and your origin
documentSelf	false	include the two docs routes in the document, under the tag docs
onWarning	console.warn	receives what could not be described, see Warnings
errors	the framework’s envelope	an error format of your own, see below
tags	none	a description for each tag, in sidebar order, see Tags

path and uiPath go under the prefix of any group docs() is mounted in, and the page finds the document there.

How a route becomes an operation

In the document	Comes from
the path	the route’s path under its groups’ prefixes: /users/:id becomes /users/{id}
operationId	docs.operationId, or the controller and field name, see Operation ids
summary, description, tags, deprecated	the route’s docs
parameters	schema.params, query, headers and cookies, required as the schema says
the request body	schema.body and bodyType; required unless bodyType is text or stream
responses	schema.response, hooks annotated with documented() and secured(), a handler annotated with documented(), and the failures the framework adds
security	secured() hooks on the route, its groups and the application

Schemas are converted through Standard Schema’s JSON Schema support, which Zod, ArkType and @tetsujs/typebox provide; Valibot needs toStandardJsonSchema from @valibot/to-json-schema.

Responses follow the route’s response map (see Responses):

• One schema is a 200. A map gives its statuses. null is a status without a body, and so is an entry with neither body nor a contentType of its own.
• A route with no schema.response is documented as 200. If its handler can answer 204, declare 204: null.
• An entry { body, headers, cookies } documents its headers, required as its schema says, and its cookies as one set-cookie header.
• An entry with contentType documents its body under that media type instead of application/json, with body as its schema, or by the type alone without one: a CSV export, a file, "text/event-stream" for sse(). See Responses. OpenAPI 3.1 cannot describe the events of a stream one by one, so a stream is documented by its type alone.
• When several sources answer with one status, the JSON body is one flat anyOf, the route’s own schema first. A body of another type is listed next to it under its own media type.

Operation ids

A generated client names its methods after the operationIds, so every one comes from a name you wrote:

Route	operationId
with docs: { operationId }	as written
in controller("Users", …) as setAvatar	usersSetAvatar
in a class UsersController as setAvatar	usersSetAvatar
in an object literal as setAvatar	setAvatar
mounted on its own, POST /auth/code	postAuthCode

Two routes with the same id are refused when the document is built, naming both: docs() stops the application at startup, and openapi() throws. Nothing is renamed for you, since that would change a method in a generated client the day a route is added. Give one of them docs.operationId, or its controller another name. On a public API, write the id on every route, so a change to it shows up in review.

Tags

A route names its tags in docs: { tags }. The tags option says what each one is:

const documentation = docs({
  info,
  tags: {
    "sign-in": "Signing in with a code sent by email, and signing out",
    me: "The signed-in user",
  },
});

Renderers list the sections in the order of the keys. A tag the routes use but tags leaves out comes after them and is reported as a warning. It is usually one tag spelled two ways, sign_in next to sign-in. A tag described but never used is reported too. Without tags, the document lists none and nothing is reported.

Responses the framework adds

The framework answers some failures by itself. They are documented on every route where they can happen, in the envelope the server sends:

Status	error	When
422, or validation.status of createApp	VALIDATION_FAILED	the route has a request schema, and a part failed it
400	MALFORMED_JSON / MALFORMED_FORM	the route reads a JSON or form body, and it could not be parsed
413	BODY_TOO_LARGE	the route reads a body, and it exceeded maxBodySize
500	INTERNAL_SERVER_ERROR	every route: an unhandled failure

See Framework error codes. A status the route declares itself is kept, and the framework’s failures for that status are listed next to it.

Every envelope, whether from the framework, a hook or the route, becomes one definition in components, named after its code: ITEM_NOT_FOUND becomes ItemNotFound. A generated client gets one type per failure. A schema counts as an envelope when its error is required and a single string. When every alternative of a status is an envelope, the status gets a discriminator on error, so a client can narrow on the code.

A status’s description comes from what answers with it: the description of the route’s schema (.describe() in Zod and ArkType, v.description() in Valibot, { description } in TypeBox), a hook’s or a handler’s documented() description, or the framework’s own. Several descriptions become a list led by each code:

- `ACCOUNT_DISABLED`: this account is disabled
- `CAPTCHA_FAILED`: the captcha token is missing or did not pass

A status with no description keeps its reason phrase, such as Not Found.

Documenting hooks

A hook that answers by itself, such as an auth check or a limiter, can say so. Every route it guards is then documented with it. secured() adds a security scheme, documented() adds responses:

import { documented, secured } from "@tetsujs/openapi";

export const auth = secured(
  hook.beforeParse((ctx) => {
    const user = verify(ctx.req.headers.get("authorization"));

    if (!user) throw new HttpError(401);

    return { user };
  }),
  { name: "bearerAuth", scheme: { type: "http", scheme: "bearer", bearerFormat: "JWT" } },
);

export const guard = documented(hook.beforeParse((ctx) => check(ctx)), {
  responses: [
    {
      status: 429,
      description: "Rate limit exceeded",
      error: "RATE_LIMITED",
      fields: { retryAfter: { type: "integer", minimum: 0 } },
      headers: { "retry-after": { schema: { type: "integer", minimum: 0 } } },
    },
  ],
});

Both return a copy of the hook with the same type, so it goes into a stack like any other. A hook mounted on a group or the application documents every route under it. Hooks from @tetsujs/rate-limit come documented already.

A response in documented() takes:

• contentType: the media type of a body that is not JSON, such as "text/html", without parameters. documented() throws on anything but a bare type or a range.
• error: the envelope’s code, documented as a const.
• fields: what the hook adds next to status, message and error, always present.
• headers: what it sets on the response, documented as possible, not required.
• message: an example of the envelope’s message.
• schema: the body, for a hook that does not answer with the envelope.

Without schema or contentType, an error status is the envelope and any other status, such as a redirect, has no body.

fields and headers are JSON Schema typed keyword by keyword (JsonSchema), so a misspelled keyword does not compile.

secured() takes:

Field	Default
name	required	the name the scheme is registered under in components
scheme	required	the OpenAPI security scheme; its type is http, apiKey, oauth2, openIdConnect or mutualTLS
scopes	none	OAuth2 scopes
status	401	the status a refused request gets
description	none	how the refusal is described
error	none	the refusal’s error code
message	none	an example of the refusal’s message

Every hook of a route runs, so the schemes of all its hooks are required together: a route behind a CSRF check and a captcha needs both. To accept one credential or another, such as a session cookie or a bearer token, check both in one hook and pass anyOf:

import { secured } from "@tetsujs/openapi";

export const caller = secured(hook.beforeParse((ctx) => ({ user: sessionOrToken(ctx) })), {
  anyOf: [cookieSession, bearerToken],
});

With a CSRF check on the same route, the document says security: [{ session: [], csrf: [] }, { bearer: [], csrf: [] }].

Documenting a handler

A handler a package hands out, such as one serving a directory of files, can describe every route it is mounted on, the way a hook describes the routes it guards. documented() takes the handler and returns a copy that answers the same way:

import { documented } from "@tetsujs/openapi";

export const files = documented(readFile, {
  hidden: true,
  responses: [
    {
      status: 200,
      description: "The file",
      contentType: "*/*",
      headers: { etag: { schema: { type: "string" } } },
    },
    { status: 304, description: "Not modified" },
    { status: 404, description: "No such file", error: "NOT_FOUND" },
  ],
});

• Its responses are the route’s own: a route that mounts it needs no schema.response, and gets no placeholder 200.
• hidden: true keeps every route that mounts it out of the document, unless the route says docs: { hidden: false }. The route’s own word wins either way.
• An arrow that wraps the handler is what the route then mounts, and it says nothing. Hide such a route, or describe it, on the route itself.

Annotate a handler whose type is already settled, such as a package’s. An arrow written inside documented() on a route does not get the route’s context and does not compile; a route of your own describes its statuses in its response map.

An error format of your own

An application can answer every failure in a format of its own with one onError hook, as Errors shows. The document cannot read that hook, so describe the same format with errors. Here the format is { code, message }:

import { docs, type ErrorFormat } from "@tetsujs/openapi";

const errors: ErrorFormat = {
  schema: ({ error, message, fields }) => ({
    type: "object",
    required: ["code", "message", ...Object.keys(fields)],
    properties: {
      code: error ? { type: "string", const: error } : { type: "string" },
      message: { type: "string", ...(message ? { examples: [message] } : {}) },
      ...fields,
    },
  }),
  discriminator: "code",
};

createApp({
  hooks: { onError: [inOurFormat] },
  routes: [api, docs({ info, errors })],
});

errors field
schema	builds the JSON Schema of one failure from { status, error, message, fields }. error is the code when known; fields holds what the failure carries besides, such as issues or retryAfter
discriminator	the top-level field that holds the code. Statuses are discriminated on it, and a route’s own envelope is recognized by it. None unless named
code	reads the code from a schema a route or hook declared, for a format that nests its code. By default, the const of the discriminator’s field

The hook and errors describe one format in two places. Keep a test that provokes each kind of failure, the unexpected one included, and checks it with assertDescribed.

Testing against the document

@tetsujs/openapi/testing checks a response a test provoked against what the document says:

import { openapi } from "@tetsujs/openapi";
import { assertDescribed } from "@tetsujs/openapi/testing";

const { document } = openapi(app, { info });

test("a wrong code is what the document says", async () => {
  const res = await request("/session", { method: "POST", body });

  await assertDescribed(document, "POST /session", res);
});

It throws unless the operation declares the status and the body fits one of that status’s alternatives, and lists every problem:

POST /session answered 403, which the document does not describe:
- error "CAPTCHA_FAILED", which its 403 does not list: ACCOUNT_DISABLED, CSRF_HEADER_REQUIRED

The second argument is the method and the path the test requested, such as "GET /users/42"; it is matched against the document’s path templates. The body is read from a clone, so the test can still read the response. Its media type is compared without regard to case, and a range in the document, such as image/* or */*, takes every type in it. The body is parsed and checked only under application/json or a +json type; under any other type, an empty body passes, as an export with no rows does.

Option	Default
validate	none	(schema, body) => true | string: checks the whole body with a JSON Schema validator of your choice, such as (schema, body) => ajv.validate(schema, body) || ajv.errorsText(). Without it, only the top level is compared: required fields and const fields
headers	none	headers the status must declare when the response carries them, such as ["retry-after"]

A header the status declares as required, such as location or set-cookie, must be on the response even without headers. See Testing.

Using the document directly

To write the document to a file in CI or feed it to a client generator, call openapi(). It takes info, servers, errors and tags, and mounts nothing:

import { openapi } from "@tetsujs/openapi";

const { document, warnings } = openapi(app, {
  info: { title: "Users API", version: "1.0.0" },
});

await Bun.write("openapi.json", JSON.stringify(document, null, 2));

Each warning has a route, such as GET /path (empty for the document as a whole), and a message.

docsPage({ ui, documentUrl, title?, assets? }) returns the page’s HTML, to serve it from a route of your own. documentUrl is where the page fetches the document from, and title defaults to "API documentation".

Warnings

A route that cannot be fully described is still documented, and the gap is reported instead of failing startup:

[openapi] POST /api/users: the body schema does not emit JSON Schema

Warnings are raised for:

• a validator that does not emit JSON Schema, or a conversion that throws;
• two routes that map to the same OpenAPI path, such as /files/* and /files/:wildcard; the second replaces the first in the document;
• a reference that leads nowhere. Recursive and named schemas emit references (#, #/$defs/…) that no longer resolve once embedded in the document: Zod’s recursive getters and .meta({ id }), ArkType’s scopes, Valibot’s lazy. TypeBox’s Type.Cyclic is described correctly;
• a tag used but not described in tags, or described and not used;
• two different security schemes under one name. The first is kept.

docs() prints each warning with console.warn, or passes it to onWarning.

The page and your origin

The page loads its renderer (Scalar, Swagger UI or Redoc) from jsDelivr and runs it on the application’s origin, with that origin’s cookies. The default files are pinned to an exact version with a Subresource Integrity hash, so the browser refuses a file the CDN changed. That still makes it someone else’s code running next to your users’ sessions.

Where the origin carries a session, serve the document alone:

const documentOnly = docs({ info, ui: false });

Or host the renderer yourself, or pin your own copy with its hash:

const pinned = docs({
  info,
  assets: {
    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.72.1/dist/browser/standalone.js",
    integrity: { script: "sha384-…" },
  },
});

curl -s <url> | openssl dgst -sha384 -binary | openssl base64 -A prints the hash; prefix it with sha384-. Swagger UI also needs style and integrity.style.

A content-security-policy that denies scripts from other origins, such as apiPolicy of @tetsujs/secure-headers, leaves the page blank. That page shows how to lift the policy for this route.

Exports

• docs and DocsController, with DocsOptions.
• openapi, with OpenApiOptions, GeneratorResult and GeneratorWarning.
• docsPage, with DocsPageOptions, DocsUi and DocsAssets.
• documented and secured, with HookDocs, HandlerDocs, DocumentedResponse, DocumentedHeader, SecurityRequirement, SecurityAlternatives, SecurityScheme and HookContributions.
• ErrorFormat and DocumentedFailure, for an error format of your own.
• JsonSchema, JsonSchemaKeywords and JsonSchemaType, for JSON Schema written by hand.
• The document’s types: OpenApiDocument, DocumentInfo, DocumentServer, PathItemObject, OperationObject, ParameterObject, ResponseObject, HeaderObject, ContentMap and TagObject.
• From @tetsujs/openapi/testing: assertDescribed, with AssertDescribedOptions.