@tetsujs/openapi 0.4.1 → 0.4.2

package/dist/src/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/json-schema.ts"],"names":[],"mappings":"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"}

package/dist/src/operation.d.ts

@@ -12,8 +12,17 @@
 import type { AppOptions, RouteTableEntry } from "@tetsujs/core";
 import type { SchemaComponents } from "./components.ts";
 import type { OperationObject } from "./document.ts";
+import type { Envelopes } from "./envelopes.ts";
 /** Describes one route. */
-export declare function operationOf(entry: RouteTableEntry, options: AppOptions, components: SchemaComponents, ids: OperationIds, warn: (message: string) => void): OperationObject;
+export declare function operationOf(entry: RouteTableEntry, options: AppOptions, components: SchemaComponents, envelopes: Envelopes, ids: OperationIds, warn: (message: string) => void): OperationObject;
+/**
+ * Records the envelopes a route declares, so that its definitions are the
+ * ones the document keeps — whichever operation refers to them first.
+ *
+ * Runs before any operation is built. A schema that cannot describe itself
+ * is skipped without a word: building the operation says so, once.
+ */
+export declare function declareEnvelopes(entry: RouteTableEntry, envelopes: Envelopes): void;
 /**
  * Hands out the `operationId` of every route in one document.
  *

package/dist/src/operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../src/operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,UAAU,EAEV,eAAe,EAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,KAAK,EAEV,eAAe,EAEhB,MAAM,eAAe,CAAC;AAKvB,2BAA2B;AAC3B,wBAAgB,WAAW,CACzB,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,gBAAgB,EAC5B,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,eAAe,CAkCjB;AAsED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC;CACtC;AAED,wBAAgB,YAAY,IAAI,YAAY,CAmB3C"}
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../src/operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,UAAU,EAEV,eAAe,EAChB,MAAM,eAAe,CAAC;AAQvB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,KAAK,EAGV,eAAe,EAEhB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,2BAA2B;AAC3B,wBAAgB,WAAW,CACzB,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,gBAAgB,EAC5B,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,eAAe,CAyCjB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,SAAS,GACnB,IAAI,CAaN;AA+GD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC;CACtC;AAED,wBAAgB,YAAY,IAAI,YAAY,CAmB3C"}

package/dist/src/page.d.ts

@@ -12,6 +12,13 @@
  * a parameter, so a self-hosted copy is one option away. Nothing is
  * fetched unless this function is called.
  *
+ * What the CDN serves runs on the application's origin, with its cookies.
+ * The default renderers are therefore pinned to an exact version and
+ * carry the hash of that file: a CDN, or a package release, that serves
+ * something else is refused by the browser rather than run. A page on an
+ * origin with a session is still somebody else's application in the
+ * user's session — which is why `docs()` can serve the document alone.
+ *
  * @module
  */
 /** The renderers this package knows how to bootstrap. */
@@ -20,6 +27,19 @@ export type DocsUi = "scalar" | "swagger-ui" | "redoc";
 export interface DocsAssets {
     readonly script: string;
     readonly style?: string;
+    /**
+     * Subresource Integrity hashes of the two files, for a copy that is not
+     * on the application's own origin: the browser runs the file only if it
+     * hashes to this. Absent, the files are loaded as they are.
+     *
+     * One line computes one:
+     * `curl -s <url> | openssl dgst -sha384 -binary | openssl base64 -A`,
+     * prefixed with `sha384-`.
+     */
+    readonly integrity?: {
+        readonly script?: string;
+        readonly style?: string;
+    };
 }
 /** What the page needs to know. */
 export interface DocsPageOptions {

package/dist/src/page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,yDAAyD;AACzD,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;AAEvD,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC9B;AAgBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAyBzD"}
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,yDAAyD;AACzD,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;AAEvD,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC9B;AAyCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAyBzD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tetsujs/openapi",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "An OpenAPI 3.1 document and docs page generated from Tetsu routes",
   "keywords": [
     "bun",
@@ -34,10 +34,10 @@
     }
   },
   "peerDependencies": {
-    "@tetsujs/core": "^0.4.1"
+    "@tetsujs/core": "^0.4.2"
   },
   "devDependencies": {
-    "@tetsujs/core": "0.4.1"
+    "@tetsujs/core": "0.4.2"
   },
   "publishConfig": {
     "access": "public"

package/src/annotations.ts

@@ -17,6 +17,7 @@
  */
 
 import type { AnyHook, AnySchema } from "@tetsujs/core";
+import type { JsonSchema } from "./json-schema.ts";
 
 /**
  * The definition of a scheme, as OpenAPI spells it.
@@ -83,6 +84,48 @@ export interface DocumentedResponse {
 
   /** An example of the envelope's `message`, for the same reason. */
   readonly message?: string;
+
+  /**
+   * Fields the hook adds to the envelope, as JSON Schema by name — the
+   * `retryAfter` of `{ ...errorBody(429, "RATE_LIMITED"), retryAfter }`.
+   *
+   * Each is documented as always present. The envelope's own `status`,
+   * `message` and `error` are not redefined by a field of the same name:
+   * `error` is what a client discriminates on, and it stays the code the
+   * hook declared. Ignored when the response has a `schema`, which says
+   * everything about the body itself.
+   *
+   * @example
+   * ```ts
+   * documented(limiter, {
+   *   responses: [
+   *     {
+   *       status: 429,
+   *       description: "Too many requests",
+   *       error: "RATE_LIMITED",
+   *       fields: { retryAfter: { type: "integer", minimum: 0 } },
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  readonly fields?: Readonly<Record<string, JsonSchema>>;
+
+  /**
+   * Headers the hook sets on this response, by name — the `retry-after`
+   * of a refusal.
+   *
+   * Documented as possible rather than required: a status several sources
+   * answer with is one response in the document, and a header one of them
+   * sets is not on the others'.
+   */
+  readonly headers?: Readonly<Record<string, DocumentedHeader>>;
+}
+
+/** A header a hook's response carries. */
+export interface DocumentedHeader {
+  readonly description?: string;
+  readonly schema: JsonSchema;
 }
 
 /**

package/src/controller.ts

@@ -22,7 +22,11 @@ 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> {
+export interface DocsOptions<
+  Path extends string,
+  UiPath extends string,
+  Ui extends DocsUi | false = DocsUi | false,
+> {
   /** Title, version and the rest of the document's `info` block. */
   readonly info: OpenApiDocument["info"];
 
@@ -35,8 +39,16 @@ export interface DocsOptions<Path extends string, UiPath extends string> {
   /** Where the page is served. Defaults to `/docs`. */
   readonly uiPath?: UiPath & ValidatePath<UiPath>;
 
-  /** Which renderer the page bootstraps. Defaults to `"scalar"`. */
-  readonly ui?: DocsUi;
+  /**
+   * Which renderer the page bootstraps. Defaults to `"scalar"`.
+   *
+   * `false` serves the document without a page — what production wants
+   * on an origin that carries a session. The page runs its renderer on the
+   * application's origin, so a renderer that is not what it should be acts
+   * in the signed-in user's name there; the document alone runs nothing.
+   * `uiPath`, `title` and `assets` are then unused.
+   */
+  readonly ui?: Ui;
 
   /** Browser title of the page. Defaults to the document's own title. */
   readonly title?: string;
@@ -69,20 +81,27 @@ export interface DocsOptions<Path extends string, UiPath extends string> {
  * 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> {
+export class DocsController<
+  Path extends string,
+  UiPath extends string,
+  Page extends boolean = true,
+> {
   /** 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">;
+  /** The page that renders it — none with `ui: false`. */
+  readonly ui: Page extends true
+    ? RouteDef<UiPath, SchemaConfig, never, undefined, "GET">
+    : undefined;
 
   private document: OpenApiDocument | undefined;
 
+  private page: string | undefined;
+
   constructor(
     private readonly options: DocsOptions<Path, UiPath>,
     documentPath: string,
     uiPath: string,
-    page: string,
   ) {
     const hidden = !options.documentSelf;
 
@@ -98,7 +117,7 @@ export class DocsController<Path extends string, UiPath extends string> {
       path: "/docs",
       docs: { summary: "Rendered documentation", tags: ["docs"], hidden },
       handler: () =>
-        new Response(page, {
+        new Response(this.page, {
           headers: { "content-type": "text/html; charset=utf-8" },
         }),
     });
@@ -113,10 +132,20 @@ export class DocsController<Path extends string, UiPath extends string> {
      * 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"];
+    this.ui = (
+      options.ui === false ? undefined : { ...ui, path: uiPath }
+    ) as this["ui"];
   }
 
-  /** Generates the document of the application this was mounted in. */
+  /**
+   * Generates the document of the application this was mounted in, and
+   * the page that renders it.
+   *
+   * The page is built here rather than with the routes because only the
+   * application knows where the document ended up: a group this controller
+   * is mounted under prefixes its path, and a page pointing at the path as
+   * configured would fetch a `404`.
+   */
   [onMount](app: App): void {
     const generated = openapi(app, {
       info: this.options.info,
@@ -125,6 +154,19 @@ export class DocsController<Path extends string, UiPath extends string> {
 
     this.document = generated.document;
 
+    const ui = this.options.ui ?? "scalar";
+    const json: unknown = this.json;
+    const served = app.entries.find((entry) => entry.def === json);
+
+    if (ui !== false && served) {
+      this.page = docsPage({
+        ui,
+        documentUrl: served.path,
+        title: this.options.title ?? this.options.info.title,
+        ...(this.options.assets ? { assets: this.options.assets } : {}),
+      });
+    }
+
     const report = this.options.onWarning ?? warn;
 
     for (const warning of generated.warnings) {
@@ -156,18 +198,15 @@ export class DocsController<Path extends string, UiPath extends string> {
 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);
+  const Ui extends DocsUi | false = "scalar",
+>(
+  options: DocsOptions<Path, UiPath, Ui>,
+): DocsController<Path, UiPath, Ui extends false ? false : true> {
+  return new DocsController(
+    options,
+    options.path ?? "/openapi.json",
+    options.uiPath ?? "/docs",
+  ) as DocsController<Path, UiPath, Ui extends false ? false : true>;
 }
 
 function warn(warning: GeneratorWarning): void {

package/src/document.ts

@@ -15,6 +15,8 @@
  * @module
  */
 
+import type { JsonSchema } from "./json-schema.ts";
+
 /** Metadata every OpenAPI document must carry. */
 export interface DocumentInfo {
   readonly title: string;
@@ -44,9 +46,16 @@ export type ContentMap = Record<
   { readonly schema?: Record<string, unknown> }
 >;
 
+/** A header a response carries. */
+export interface HeaderObject {
+  readonly description?: string;
+  readonly schema: JsonSchema;
+}
+
 /** One response of an operation. */
 export interface ResponseObject {
   readonly description: string;
+  readonly headers?: Record<string, HeaderObject>;
   readonly content?: ContentMap;
 }
 

package/src/emit.ts

@@ -20,13 +20,15 @@ import { toJsonSchema } from "@tetsujs/core";
 const target = { target: "draft-2020-12" } as const;
 
 /**
- * A JSON Schema as the generator reads it: any keyword, with the two it
+ * A JSON Schema as the generator reads it: any keyword, with the ones it
  * looks into named, so reading them does not depend on the reader's
  * `noPropertyAccessFromIndexSignature`.
  */
 export interface JsonSchemaObject {
   properties?: unknown;
   required?: unknown;
+  anyOf?: unknown;
+  oneOf?: unknown;
   [keyword: string]: unknown;
 }
 

package/src/envelopes.ts

@@ -0,0 +1,242 @@
+/**
+ * Error envelopes, one definition per status and code.
+ *
+ * An envelope reaches a document from four directions: a route's response
+ * map, a hook's annotation, a guard's security requirement, and the
+ * framework's own failures. Each used to be described where it arrived —
+ * a route's inline, the rest by reference — so one `UNAUTHORIZED` could be
+ * listed twice under one status, once as a `$ref` and once as the same
+ * shape without a name, and a generated client got a named type next to an
+ * anonymous twin.
+ *
+ * Here every envelope, whoever declared it, becomes a reference to the
+ * one definition of its status and code. That is also what makes a status
+ * discriminable: a client can branch on `error` only if every code under
+ * the status has exactly one shape.
+ *
+ * The route's definition wins. It is the author's own contract — usually
+ * the stricter one, a validator's `additionalProperties: false` — where a
+ * hook's is the framework's generic envelope. The routes are therefore
+ * read first, before any operation is built, so the winner does not depend
+ * on which route happens to come first in the table.
+ *
+ * Internal to the package.
+ *
+ * @module
+ */
+
+import type { SchemaComponents, SchemaRef } from "./components.ts";
+import { failureName } from "./components.ts";
+import type { JsonSchemaObject } from "./emit.ts";
+
+/** The definitions of every envelope of one document. */
+export interface Envelopes {
+  /**
+   * Records a route's definition, before anything is referenced. The first
+   * route to declare a status and code defines it.
+   */
+  declare(status: number, code: string, schema: JsonSchemaObject): void;
+
+  /**
+   * The reference to the definition of a status and code.
+   *
+   * `schema` is how the caller describes it. When a definition already
+   * exists, that is what is referenced; if the caller's differs from it
+   * in fields, `warn` hears about it — once per document, not once per
+   * operation the hook runs on.
+   */
+  ref(
+    status: number,
+    code: string,
+    schema: JsonSchemaObject,
+    warn: (message: string) => void,
+  ): SchemaRef;
+
+  /**
+   * The code a reference stands for, when it is one this handed out — what
+   * a discriminator maps back from.
+   */
+  codeOf(ref: string): string | undefined;
+}
+
+export function envelopes(components: SchemaComponents): Envelopes {
+  const declared = new Map<string, JsonSchemaObject>();
+  const defined = new Map<string, JsonSchemaObject>();
+  const refs = new Map<string, SchemaRef>();
+  const codes = new Map<string, string>();
+  const names = new Map<string, string>();
+  const reported = new Set<string>();
+
+  return {
+    declare(status, code, schema) {
+      const key = keyOf(status, code);
+
+      if (!declared.has(key)) {
+        declared.set(key, schema);
+      }
+    },
+
+    ref(status, code, schema, warn) {
+      const key = keyOf(status, code);
+      const definition = declared.get(key) ?? defined.get(key) ?? schema;
+
+      defined.set(key, definition);
+
+      const difference = differenceOf(definition, schema);
+
+      if (difference && !reported.has(`${key} ${difference}`)) {
+        reported.add(`${key} ${difference}`);
+        warn(
+          `the ${status} "${code}" is described by one definition in the document, and a definition that differs from it in ${difference} is not described`,
+        );
+      }
+
+      const existing = refs.get(key);
+
+      if (existing) {
+        return existing;
+      }
+
+      const created = components.ref(nameOf(status, code), definition);
+
+      refs.set(key, created);
+      codes.set(created.$ref, code);
+
+      return created;
+    },
+
+    codeOf(ref) {
+      return codes.get(ref);
+    },
+  };
+
+  /**
+   * The name a status and code are defined under: the code's, unless the
+   * same code under another status has it already, in which case the
+   * status tells the two apart — `Invalid` and `Invalid409`.
+   */
+  function nameOf(status: number, code: string): string {
+    const name = failureName(status, code);
+    const holder = names.get(name);
+
+    if (holder === undefined || holder === keyOf(status, code)) {
+      names.set(name, keyOf(status, code));
+
+      return name;
+    }
+
+    return `${name}${status}`;
+  }
+}
+
+/**
+ * The error code of a schema that is an envelope: an object whose `error`
+ * is required and holds one string — a `const`, or an `enum` of one value.
+ *
+ * Read off what the validator emitted, not off a declaration: the route
+ * has no other way to say which of its responses is an envelope, and the
+ * shape is what a client would branch on anyway.
+ */
+export function envelopeCode(schema: JsonSchemaObject): string | undefined {
+  const required = Array.isArray(schema.required) ? schema.required : [];
+
+  if (!required.includes("error")) {
+    return undefined;
+  }
+
+  const error = (
+    schema.properties as
+      | { error?: { const?: unknown; enum?: unknown } }
+      | undefined
+  )?.error;
+
+  if (typeof error?.const === "string") {
+    return error.const;
+  }
+
+  if (
+    Array.isArray(error?.enum) &&
+    error.enum.length === 1 &&
+    typeof error.enum[0] === "string"
+  ) {
+    return error.enum[0];
+  }
+
+  return undefined;
+}
+
+/**
+ * The alternatives a schema stands for, as a list the status's own union
+ * can take in.
+ *
+ * `anyOf` nested in `anyOf` says nothing its branches do not say side by
+ * side, so a schema that is only an `anyOf` is replaced by its branches.
+ * A `oneOf` is different — "exactly one" of two overlapping shapes refuses
+ * what both accept — and is taken apart only when its branches cannot
+ * overlap: envelopes with a different code each. A schema with anything
+ * beside its union, a `title` or a `$defs`, is left whole: those keywords
+ * belong to the union, and would be lost with it.
+ */
+export function branchesOf(schema: JsonSchemaObject): JsonSchemaObject[] {
+  const keys = Object.keys(schema);
+
+  if (keys.length !== 1) {
+    return [schema];
+  }
+
+  if (Array.isArray(schema.anyOf)) {
+    return (schema.anyOf as JsonSchemaObject[]).flatMap(branchesOf);
+  }
+
+  if (Array.isArray(schema.oneOf)) {
+    const branches = (schema.oneOf as JsonSchemaObject[]).flatMap(branchesOf);
+    const codes = branches.map(envelopeCode);
+
+    if (
+      codes.every((code) => code !== undefined) &&
+      new Set(codes).size === codes.length
+    ) {
+      return branches;
+    }
+  }
+
+  return [schema];
+}
+
+function keyOf(status: number, code: string): string {
+  return `${status} ${code}`;
+}
+
+/**
+ * How two definitions of one envelope differ in what a client reads: the
+ * fields one has and the other does not, or which of them are required.
+ * Wording — a `message` example, `number` against `integer` for the
+ * status — is not a difference a client would notice, and is not one.
+ */
+function differenceOf(
+  kept: JsonSchemaObject,
+  other: JsonSchemaObject,
+): string | undefined {
+  const fields = (schema: JsonSchemaObject): string[] =>
+    Object.keys((schema.properties as Record<string, unknown>) ?? {});
+
+  const keptFields = fields(kept);
+  const otherFields = fields(other);
+
+  const missing = otherFields.filter((name) => !keptFields.includes(name));
+  const extra = keptFields.filter((name) => !otherFields.includes(name));
+  const changed = [...missing, ...extra];
+
+  if (changed.length > 0) {
+    return `fields: ${changed.join(", ")}`;
+  }
+
+  const required = (schema: JsonSchemaObject): string =>
+    JSON.stringify(
+      [...(Array.isArray(schema.required) ? schema.required : [])].sort(),
+    );
+
+  return required(kept) === required(other)
+    ? undefined
+    : "which fields are required";
+}

package/src/index.ts

@@ -23,10 +23,12 @@ 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 { envelopes as envelopeDefinitions } from "./envelopes.ts";
+import { declareEnvelopes, operationIds, operationOf } from "./operation.ts";
 import { toTemplate } from "./parameters.ts";
 
 export type {
+  DocumentedHeader,
   DocumentedResponse,
   HookContributions,
   HookDocs,
@@ -41,12 +43,18 @@ export type {
   ContentMap,
   DocumentInfo,
   DocumentServer,
+  HeaderObject,
   OpenApiDocument,
   OperationObject,
   ParameterObject,
   PathItemObject,
   ResponseObject,
 } from "./document.ts";
+export type {
+  JsonSchema,
+  JsonSchemaKeywords,
+  JsonSchemaType,
+} from "./json-schema.ts";
 export type { DocsAssets, DocsPageOptions, DocsUi } from "./page.ts";
 export { docsPage } from "./page.ts";
 
@@ -103,7 +111,15 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
   const warnings: GeneratorWarning[] = [];
   const schemes: Record<string, unknown> = {};
   const components = schemaComponents();
+  const envelopes = envelopeDefinitions(components);
   const ids = operationIds();
+  const described = app.entries.filter(
+    (entry) => !entry.ws && !entry.def.docs?.hidden,
+  );
+
+  for (const entry of described) {
+    declareEnvelopes(entry, envelopes);
+  }
 
   // Which route already occupies each slot of the document. Two routes the
   // router keeps apart can still meet here, because a template says less
@@ -114,11 +130,7 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
   // 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;
-    }
-
+  for (const entry of described) {
     const template = toTemplate(entry.path);
     const route = `${entry.method} ${entry.path}`;
 
@@ -126,6 +138,7 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
       entry,
       app.options,
       components,
+      envelopes,
       ids,
       (message) => {
         warnings.push({ route, message });