@tetsujs/openapi 0.1.0

package/src/components.ts

@@ -0,0 +1,90 @@
+/**
+ * The document's `components/schemas` section.
+ *
+ * The failures the framework fills in repeat across every operation — a
+ * `500` on all of them, a `413` on every route with a body — and inlining
+ * the same envelope each time makes a document that is mostly boilerplate.
+ * They are defined once here and referenced with `$ref`, which is also how
+ * a client generator ends up with one `MalformedJson` type instead of one
+ * per endpoint.
+ *
+ * Only the framework's own shapes go here. A schema that came from a
+ * validator is still inlined: it is the author's, it has no name the
+ * generator could give it, and `$ref` would invent one.
+ *
+ * @module
+ */
+
+/** A reference to a definition in `components/schemas`. */
+export interface SchemaRef {
+  readonly $ref: string;
+}
+
+/** The definitions collected while generating a document. */
+export interface SchemaComponents {
+  /**
+   * Registers a schema and returns the reference to it.
+   *
+   * Identical schemas share one definition, whatever name each caller
+   * asked for; different schemas that want the same name get a numbered
+   * one, so a document is never silently wrong about what a `$ref` points
+   * at.
+   */
+  ref(preferred: string, schema: Record<string, unknown>): SchemaRef;
+
+  /** What was registered, in registration order. */
+  readonly schemas: Record<string, unknown>;
+}
+
+export function schemaComponents(): SchemaComponents {
+  const schemas: Record<string, unknown> = {};
+  const registered = new Map<string, string>();
+
+  return {
+    schemas,
+
+    ref(preferred: string, schema: Record<string, unknown>): SchemaRef {
+      const fingerprint = JSON.stringify(schema);
+      const already = registered.get(fingerprint);
+
+      if (already) {
+        return { $ref: `#/components/schemas/${already}` };
+      }
+
+      let name = preferred;
+
+      for (let attempt = 2; name in schemas; attempt += 1) {
+        name = `${preferred}${attempt}`;
+      }
+
+      schemas[name] = schema;
+      registered.set(fingerprint, name);
+
+      return { $ref: `#/components/schemas/${name}` };
+    },
+  };
+}
+
+/**
+ * The name a failure is defined under: its `error` code in PascalCase —
+ * `MALFORMED_JSON` becomes `MalformedJson` — so the definition and the code
+ * a client branches on read as the same thing.
+ *
+ * A failure whose code only the hook knows, and which the hook did not
+ * declare, is named after its status instead.
+ */
+export function failureName(status: number, error?: string): string {
+  const name = (error ?? "")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+
+  // A code with nothing ASCII in it sanitizes to nothing — a code in
+  // Cyrillic or Japanese, or one that is all punctuation. That is the same
+  // situation as no code at all, and gets the same name: the alternative
+  // was a component keyed `""`, which the specification does not allow, and
+  // a second such code keyed `"2"` by the collision numbering below it.
+  return name || `Failure${status}`;
+}

package/src/controller.ts

@@ -0,0 +1,175 @@
+/**
+ * The documentation endpoints as a mountable controller.
+ *
+ * `openapi()` returns data and mounts nothing, which is the right default
+ * for a generator but a chore in the ordinary case: every application ends
+ * up writing the same controller, holding the same application, to serve
+ * the same two routes. {@link docs} is that controller, written once.
+ *
+ * It is a controller like any other — mounted in `routes`, groupable,
+ * hookable — that receives the application through `onMount` and generates
+ * the document from it at startup.
+ *
+ * @module
+ */
+
+import type { App, RouteDef, SchemaConfig, ValidatePath } from "@tetsujs/core";
+import { onMount, route } from "@tetsujs/core";
+import type { OpenApiDocument } from "./document.ts";
+import type { GeneratorWarning } from "./index.ts";
+import { openapi } from "./index.ts";
+import type { DocsAssets, DocsUi } from "./page.ts";
+import { docsPage } from "./page.ts";
+
+/** What the documentation controller serves, and from where. */
+export interface DocsOptions<Path extends string, UiPath extends string> {
+  /** Title, version and the rest of the document's `info` block. */
+  readonly info: OpenApiDocument["info"];
+
+  /** Servers the API is reachable at. */
+  readonly servers?: OpenApiDocument["servers"];
+
+  /** Where the document is served. Defaults to `/openapi.json`. */
+  readonly path?: Path & ValidatePath<Path>;
+
+  /** Where the page is served. Defaults to `/docs`. */
+  readonly uiPath?: UiPath & ValidatePath<UiPath>;
+
+  /** Which renderer the page bootstraps. Defaults to `"scalar"`. */
+  readonly ui?: DocsUi;
+
+  /** Browser title of the page. Defaults to the document's own title. */
+  readonly title?: string;
+
+  /** Overrides the renderer's CDN URLs, for a pinned or self-hosted copy. */
+  readonly assets?: DocsAssets;
+
+  /**
+   * Documents the two endpoints this controller serves.
+   *
+   * Off by default: a reader who is looking at the document has already
+   * found the document, and an operation for "the page you are reading"
+   * is one a generated client would happily produce a method for.
+   */
+  readonly documentSelf?: boolean;
+
+  /**
+   * What to do with what the generator could not describe.
+   *
+   * Defaults to one `console.warn` per warning, at startup — a document
+   * that silently omits a body is worse than a noisy one.
+   */
+  readonly onWarning?: (warning: GeneratorWarning) => void;
+}
+
+/**
+ * The controller {@link docs} returns: two routes and the `onMount` that
+ * fills them.
+ *
+ * Instantiated through the factory, never directly — the routes carry the
+ * configured paths in their types, which only the factory can infer.
+ */
+export class DocsController<Path extends string, UiPath extends string> {
+  /** The document itself, as `application/json`. */
+  readonly json: RouteDef<Path, SchemaConfig, never, undefined, "GET">;
+
+  /** The page that renders it. */
+  readonly ui: RouteDef<UiPath, SchemaConfig, never, undefined, "GET">;
+
+  private document: OpenApiDocument | undefined;
+
+  constructor(
+    private readonly options: DocsOptions<Path, UiPath>,
+    documentPath: string,
+    uiPath: string,
+    page: string,
+  ) {
+    const hidden = !options.documentSelf;
+
+    const json = route({
+      method: "GET",
+      path: "/openapi.json",
+      docs: { summary: "This document", tags: ["docs"], hidden },
+      handler: () => this.document,
+    });
+
+    const ui = route({
+      method: "GET",
+      path: "/docs",
+      docs: { summary: "Rendered documentation", tags: ["docs"], hidden },
+      handler: () =>
+        new Response(page, {
+          headers: { "content-type": "text/html; charset=utf-8" },
+        }),
+    });
+
+    /**
+     * The configured paths, put back on the routes.
+     *
+     * `route()` validates its path at the type level, and that check
+     * cannot be satisfied by a type variable — `ValidatePath<Path>` stays
+     * unresolved while `Path` is generic. The routes are therefore built
+     * with the default literals and re-typed here, which is also where the
+     * configured path lands at runtime.
+     */
+    this.json = { ...json, path: documentPath } as unknown as this["json"];
+    this.ui = { ...ui, path: uiPath } as unknown as this["ui"];
+  }
+
+  /** Generates the document of the application this was mounted in. */
+  [onMount](app: App): void {
+    const generated = openapi(app, {
+      info: this.options.info,
+      ...(this.options.servers ? { servers: this.options.servers } : {}),
+    });
+
+    this.document = generated.document;
+
+    const report = this.options.onWarning ?? warn;
+
+    for (const warning of generated.warnings) {
+      report(warning);
+    }
+  }
+}
+
+/**
+ * The documentation of an application, as a controller to mount.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   routes: [
+ *     group("/api", { children: [new UsersController(users)] }),
+ *     docs({ info: { title: "Users API", version: "1.0.0" } }),
+ *   ],
+ * });
+ * ```
+ *
+ * The document is generated once, at startup, from the application the
+ * controller was mounted in. Its own two routes stay out of it — pass
+ * `documentSelf` to put them in.
+ *
+ * The page loads its renderer from a CDN; see {@link docsPage} for the
+ * trade and for how to point it at a self-hosted copy.
+ */
+export function docs<
+  const Path extends string = "/openapi.json",
+  const UiPath extends string = "/docs",
+>(options: DocsOptions<Path, UiPath>): DocsController<Path, UiPath> {
+  const documentPath = options.path ?? "/openapi.json";
+  const uiPath = options.uiPath ?? "/docs";
+
+  const page = docsPage({
+    ui: options.ui ?? "scalar",
+    documentUrl: documentPath,
+    title: options.title ?? options.info.title,
+    ...(options.assets ? { assets: options.assets } : {}),
+  });
+
+  return new DocsController(options, documentPath, uiPath, page);
+}
+
+function warn(warning: GeneratorWarning): void {
+  console.warn(`[openapi] ${warning.route}: ${warning.message}`);
+}

package/src/document.ts

@@ -0,0 +1,90 @@
+/**
+ * The shape of the documents this package produces.
+ *
+ * Typed only as far as the generator fills it in: an OpenAPI document is
+ * far larger than what a route table can honestly describe, and declaring
+ * the rest would promise support that does not exist. Everything typed
+ * here is emitted; everything a caller adds by hand passes through the
+ * index signatures.
+ *
+ * OpenAPI 3.1 only. It is JSON Schema 2020-12 verbatim, which is what
+ * validators emit through Standard Schema — 3.0 would mean converting the
+ * dialect and being subtly wrong about `nullable`, `examples` and binary
+ * payloads.
+ *
+ * @module
+ */
+
+/** Metadata every OpenAPI document must carry. */
+export interface DocumentInfo {
+  readonly title: string;
+  readonly version: string;
+  readonly description?: string;
+  readonly [key: string]: unknown;
+}
+
+/** A server the API is reachable at. */
+export interface DocumentServer {
+  readonly url: string;
+  readonly description?: string;
+}
+
+/** One request parameter: a path segment, a query key or a header. */
+export interface ParameterObject {
+  readonly name: string;
+  readonly in: "path" | "query" | "header" | "cookie";
+  readonly required: boolean;
+  readonly description?: string;
+  readonly schema?: Record<string, unknown>;
+}
+
+/** A body or response payload, keyed by media type. */
+export type ContentMap = Record<
+  string,
+  { readonly schema?: Record<string, unknown> }
+>;
+
+/** One response of an operation. */
+export interface ResponseObject {
+  readonly description: string;
+  readonly content?: ContentMap;
+}
+
+/** One endpoint: a method on a path. */
+export interface OperationObject {
+  readonly operationId: string;
+  readonly summary?: string;
+  readonly description?: string;
+  readonly tags?: readonly string[];
+  readonly deprecated?: boolean;
+  readonly parameters?: readonly ParameterObject[];
+  readonly requestBody?: {
+    readonly required: boolean;
+    readonly content: ContentMap;
+  };
+  readonly security?: readonly Record<string, readonly string[]>[];
+  readonly responses: Record<string, ResponseObject>;
+}
+
+/** Every operation declared on one path template. */
+export type PathItemObject = Record<string, OperationObject>;
+
+/** The generated document. */
+export interface OpenApiDocument {
+  readonly openapi: "3.1.0";
+  readonly info: DocumentInfo;
+  readonly servers?: readonly DocumentServer[];
+  readonly paths: Record<string, PathItemObject>;
+
+  /**
+   * What the operations refer to rather than repeat: the security schemes
+   * the guards registered, and the failure envelopes the framework fills
+   * in. Absent when neither has anything to say.
+   */
+  readonly components?: {
+    readonly securitySchemes?: Record<string, unknown>;
+    readonly schemas?: Record<string, unknown>;
+  };
+
+  readonly [key: string]: unknown;
+}

package/src/emit.ts

@@ -0,0 +1,98 @@
+/**
+ * Asking a schema to describe itself, without letting it stop the document.
+ *
+ * Internal to the package.
+ *
+ * @module
+ */
+
+import { toJsonSchema } from "@tetsujs/core";
+
+/**
+ * The JSON Schema dialect a schema is asked for.
+ *
+ * OpenAPI 3.1 takes JSON Schema 2020-12 as it is, and `draft-2020-12` is a
+ * target the Standard JSON Schema specification names — so every library
+ * that implements it answers. This used to be `openapi-3.1`, which only
+ * Zod accepts: ArkType and Valibot refused it, and their bodies went into
+ * the document without a shape and with a warning each.
+ */
+const target = { target: "draft-2020-12" } as const;
+
+/**
+ * A JSON Schema as the generator reads it: any keyword, with the two it
+ * looks into named, so reading them does not depend on the reader's
+ * `noPropertyAccessFromIndexSignature`.
+ */
+export interface JsonSchemaObject {
+  properties?: unknown;
+  required?: unknown;
+  [keyword: string]: unknown;
+}
+
+/** Which shape of a schema to describe: what arrives, or what leaves. */
+type Direction = "input" | "output";
+
+/**
+ * The JSON Schema of a declaration, or `undefined` and a warning saying why.
+ *
+ * A schema can fail to describe itself in two ways, and the generator owes
+ * the same answer to both: an adapter without JSON Schema support returns
+ * nothing, and an adapter that has it can still throw — a converter meeting
+ * a shape it cannot express, a structure too deep to walk, a `$ref` that
+ * leads back to where it started.
+ *
+ * Only the first was handled, and the difference between them is not the
+ * document: it is whether the application starts at all. `docs()` builds
+ * the document from `onMount`, which `createApp` calls while it is still
+ * assembling itself, so an escaping error is not a gap in a description —
+ * it is a server that never listens, over a route that would have worked.
+ *
+ * `subject` names the declaration for the message, as the reader of a
+ * warning would name it: `"the body"`, `"a response"`.
+ */
+export function emitted(
+  schema: unknown,
+  subject: string,
+  warn: (message: string) => void,
+  direction: Direction = "output",
+): JsonSchemaObject | undefined {
+  let described: JsonSchemaObject | undefined;
+
+  try {
+    described = toJsonSchema(schema, target, direction);
+  } catch (error) {
+    warn(`${subject} schema failed to emit JSON Schema: ${reason(error)}`);
+
+    return undefined;
+  }
+
+  if (!described) {
+    warn(`${subject} schema does not emit JSON Schema`);
+
+    return undefined;
+  }
+
+  return withoutDialect(described);
+}
+
+/**
+ * A schema as the document embeds it: without its own `$schema`.
+ *
+ * Asked for draft 2020-12, Zod and ArkType name the dialect at the root of
+ * every schema they emit. The document declares it once for all of them,
+ * and the same line on every body and response is noise.
+ */
+function withoutDialect(schema: JsonSchemaObject): JsonSchemaObject {
+  if (!("$schema" in schema)) {
+    return schema;
+  }
+
+  const { $schema: _, ...rest } = schema;
+
+  return rest;
+}
+
+function reason(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/index.ts

@@ -0,0 +1,203 @@
+/**
+ * OpenAPI generation for the framework.
+ *
+ * Reads a compiled application — `app.entries` and the options it actually
+ * runs with — and returns an OpenAPI 3.1 document. Nothing is registered,
+ * served or mutated: the document is data, and serving it is a route the
+ * application declares like any other.
+ *
+ * Serving it is a route the application declares — or `docs()`, the
+ * controller that declares those routes for you.
+ *
+ * @example
+ * ```ts
+ * const { document, warnings } = openapi(app, {
+ *   info: { title: "Users API", version: "1.0.0" },
+ * });
+ * ```
+ *
+ * @module
+ */
+
+import type { App } from "@tetsujs/core";
+import { contributionsOf } from "./annotations.ts";
+import { schemaComponents } from "./components.ts";
+import type { OpenApiDocument, PathItemObject } from "./document.ts";
+import { operationIds, operationOf } from "./operation.ts";
+import { toTemplate } from "./parameters.ts";
+
+export type {
+  DocumentedResponse,
+  HookContributions,
+  HookDocs,
+  SecurityRequirement,
+  SecurityScheme,
+} from "./annotations.ts";
+export { documented, secured } from "./annotations.ts";
+export type { DocsOptions } from "./controller.ts";
+export { DocsController, docs } from "./controller.ts";
+export type {
+  ContentMap,
+  DocumentInfo,
+  DocumentServer,
+  OpenApiDocument,
+  OperationObject,
+  ParameterObject,
+  PathItemObject,
+  ResponseObject,
+} from "./document.ts";
+export type { DocsAssets, DocsPageOptions, DocsUi } from "./page.ts";
+export { docsPage } from "./page.ts";
+
+/**
+ * What the generator cannot read off the application.
+ */
+export interface OpenApiOptions {
+  /** Title, version and the rest of the document's `info` block. */
+  readonly info: OpenApiDocument["info"];
+
+  /** Servers the API is reachable at. */
+  readonly servers?: OpenApiDocument["servers"];
+}
+
+/**
+ * What the generator could not describe faithfully.
+ *
+ * Each entry names a route and what was missing — almost always a schema
+ * from a validator that emits no JSON Schema. Documentation that silently
+ * omits a body is worse than documentation that says it does not know, so
+ * these are returned rather than swallowed.
+ */
+export interface GeneratorWarning {
+  readonly route: string;
+  readonly message: string;
+}
+
+/** A generated document together with what could not be described. */
+export interface GeneratorResult {
+  readonly document: OpenApiDocument;
+  readonly warnings: readonly GeneratorWarning[];
+}
+
+/**
+ * Generates the OpenAPI document of an application.
+ *
+ * Socket endpoints are skipped: a handshake is a `GET` in the table, but
+ * OpenAPI has no way to describe what happens after it, and documenting
+ * the upgrade as an ordinary operation would describe a request that
+ * clients must not make. AsyncAPI is that format, and a separate document.
+ *
+ * So are routes marked `docs: { hidden: true }`, and everything they would
+ * have contributed with them: a security scheme only a hidden route
+ * requires has nothing left to describe.
+ *
+ * Every route of the table becomes an operation under its path template,
+ * with the parameters, body and responses its schemas describe. What the
+ * framework itself can answer — a validation failure, an unparsable body,
+ * a body over the limit — is filled in from the options the application
+ * runs with, so the document states the status actually configured.
+ */
+export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
+  const paths: Record<string, PathItemObject> = {};
+  const warnings: GeneratorWarning[] = [];
+  const schemes: Record<string, unknown> = {};
+  const components = schemaComponents();
+  const ids = operationIds();
+
+  // Which route already occupies each slot of the document. Two routes the
+  // router keeps apart can still meet here, because a template says less
+  // than a path does: `/files/*` and `/files/:wildcard` both become
+  // `/files/{wildcard}`, and a literal `/users/{id}` — which Bun matches as
+  // the string it is — is spelled the same as `/users/:id`. The second one
+  // then replaces the first, and the document quietly loses an endpoint
+  // that works. It still loses it; it no longer does so without saying.
+  const occupied = new Map<string, string>();
+
+  for (const entry of app.entries) {
+    if (entry.ws || entry.def.docs?.hidden) {
+      continue;
+    }
+
+    const template = toTemplate(entry.path);
+    const route = `${entry.method} ${entry.path}`;
+
+    const operation = operationOf(
+      entry,
+      app.options,
+      components,
+      ids,
+      (message) => {
+        warnings.push({ route, message });
+      },
+    );
+
+    // First definition wins, as it does among the hooks of one route: a
+    // name is the identity of a scheme, and the operations that reference
+    // it say only the name. A second, different scheme under that name
+    // cannot be described without renaming it out from under everything
+    // already pointing at it, so it is refused rather than silently
+    // swapped in — which used to make every earlier operation describe an
+    // authentication its route does not perform.
+    for (const requirement of contributionsOf(entry.hooks).security) {
+      const defined = schemes[requirement.name];
+
+      if (defined === undefined) {
+        schemes[requirement.name] = requirement.scheme;
+
+        continue;
+      }
+
+      if (JSON.stringify(defined) !== JSON.stringify(requirement.scheme)) {
+        warnings.push({
+          route,
+          message: `the security scheme "${requirement.name}" is already defined differently; this definition is ignored`,
+        });
+      }
+    }
+
+    const slot = `${entry.method.toLowerCase()} ${template}`;
+    const taken = occupied.get(slot);
+
+    if (taken) {
+      warnings.push({
+        route,
+        message: `${template} is already described by ${taken}, whose operation this replaces`,
+      });
+    }
+
+    occupied.set(slot, route);
+
+    paths[template] = {
+      ...paths[template],
+      [entry.method.toLowerCase()]: operation,
+    };
+  }
+
+  return {
+    document: {
+      openapi: "3.1.0",
+      info: options.info,
+      ...(options.servers ? { servers: options.servers } : {}),
+      paths,
+      ...componentsOf(schemes, components.schemas),
+    },
+    warnings,
+  };
+}
+
+/**
+ * The `components` block, present only when something goes in it: the
+ * security schemes the guards registered, and the failure envelopes the
+ * operations refer to.
+ */
+function componentsOf(
+  securitySchemes: Record<string, unknown>,
+  schemas: Record<string, unknown>,
+): { components?: Record<string, unknown> } {
+  const components = {
+    ...(Object.keys(securitySchemes).length > 0 ? { securitySchemes } : {}),
+    ...(Object.keys(schemas).length > 0 ? { schemas } : {}),
+  };
+
+  return Object.keys(components).length > 0 ? { components } : {};
+}