@tetsujs/openapi 0.4.1 → 0.5.0

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

@@ -0,0 +1,91 @@
+/**
+ * JSON Schema 2020-12, as written by hand.
+ *
+ * Every other schema in a document comes from a validator, which describes
+ * itself. What a hook adds to its answer — a field next to the envelope, a
+ * header — has no validator behind it, and is written as JSON Schema
+ * directly. Typed closed, keyword by keyword, so that an editor offers the
+ * keywords and a misspelled one is an error: an open record would take
+ * `minimun` and `{ type: "int" }` and put them in the document as they are.
+ *
+ * Closed on purpose, not by omission. The generator asks every schema for
+ * the 2020-12 dialect, and a dialect's keywords are a fixed list. The one
+ * open door is what OpenAPI itself allows in a schema — extensions, named
+ * `x-` — and no misspelling of a keyword starts with it.
+ *
+ * @module
+ */
+/** A primitive type name of JSON Schema. */
+export type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+/**
+ * A schema: an object of keywords, or `true` and `false` — the schemas
+ * everything and nothing satisfy.
+ *
+ * @example
+ * ```ts
+ * const retryAfter: JsonSchema = { type: "integer", minimum: 0 };
+ * ```
+ */
+export type JsonSchema = JsonSchemaKeywords | boolean;
+/** The keywords of JSON Schema 2020-12. */
+export interface JsonSchemaKeywords {
+    readonly $schema?: string;
+    readonly $id?: string;
+    readonly $ref?: string;
+    readonly $anchor?: string;
+    readonly $dynamicRef?: string;
+    readonly $dynamicAnchor?: string;
+    readonly $vocabulary?: Readonly<Record<string, boolean>>;
+    readonly $comment?: string;
+    readonly $defs?: Readonly<Record<string, JsonSchema>>;
+    readonly type?: JsonSchemaType | readonly JsonSchemaType[];
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly multipleOf?: number;
+    readonly maximum?: number;
+    readonly exclusiveMaximum?: number;
+    readonly minimum?: number;
+    readonly exclusiveMinimum?: number;
+    readonly maxLength?: number;
+    readonly minLength?: number;
+    readonly pattern?: string;
+    readonly format?: string;
+    readonly contentEncoding?: string;
+    readonly contentMediaType?: string;
+    readonly contentSchema?: JsonSchema;
+    readonly prefixItems?: readonly JsonSchema[];
+    readonly items?: JsonSchema;
+    readonly contains?: JsonSchema;
+    readonly maxItems?: number;
+    readonly minItems?: number;
+    readonly uniqueItems?: boolean;
+    readonly maxContains?: number;
+    readonly minContains?: number;
+    readonly unevaluatedItems?: JsonSchema;
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly patternProperties?: Readonly<Record<string, JsonSchema>>;
+    readonly additionalProperties?: JsonSchema;
+    readonly unevaluatedProperties?: JsonSchema;
+    readonly propertyNames?: JsonSchema;
+    readonly required?: readonly string[];
+    readonly dependentRequired?: Readonly<Record<string, readonly string[]>>;
+    readonly dependentSchemas?: Readonly<Record<string, JsonSchema>>;
+    readonly maxProperties?: number;
+    readonly minProperties?: number;
+    readonly allOf?: readonly JsonSchema[];
+    readonly anyOf?: readonly JsonSchema[];
+    readonly oneOf?: readonly JsonSchema[];
+    readonly not?: JsonSchema;
+    readonly if?: JsonSchema;
+    readonly then?: JsonSchema;
+    readonly else?: JsonSchema;
+    readonly title?: string;
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly deprecated?: boolean;
+    readonly readOnly?: boolean;
+    readonly writeOnly?: boolean;
+    readonly examples?: readonly unknown[];
+    readonly [extension: `x-${string}`]: unknown;
+}
+//# sourceMappingURL=json-schema.d.ts.map

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;AAKhD,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,CAeN;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.5.0",
   "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.5.0"
   },
   "devDependencies": {
-    "@tetsujs/core": "0.4.1"
+    "@tetsujs/core": "0.5.0"
   },
   "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

@@ -16,27 +16,46 @@
 import type { App, RouteDef, SchemaConfig, ValidatePath } from "@tetsujs/core";
 import { onMount, route } from "@tetsujs/core";
 import type { OpenApiDocument } from "./document.ts";
+import type { ErrorFormat } from "./errors.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> {
+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"];
 
   /** Servers the API is reachable at. */
   readonly servers?: OpenApiDocument["servers"];
 
+  /**
+   * How the application's errors look, when not like the framework's
+   * envelope — see `errors` on {@link openapi}.
+   */
+  readonly errors?: ErrorFormat;
+
   /** 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;
+  /**
+   * 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 +88,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 +124,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,18 +139,42 @@ 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,
       ...(this.options.servers ? { servers: this.options.servers } : {}),
+      ...(this.options.errors ? { errors: this.options.errors } : {}),
     });
 
     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 +206,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;
 }