@tetsujs/openapi 0.6.1 → 0.6.3

package/dist/src/media.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Media types, as the document's `content` keys them.
+ *
+ * The core checks a route's `contentType` when the route is declared; a
+ * response annotated with `documented()` reaches the document without the
+ * core seeing it, so the same rule is applied here, when it is annotated.
+ *
+ * @module
+ */
+/**
+ * Whether a value is a media type or a range of them, as a document's
+ * `content` names it: `text/csv`, `image/*`, the range of every type — and
+ * no parameters, which a key would carry into every comparison with what a
+ * response says.
+ */
+export declare function isMediaType(value: unknown): value is string;
+/**
+ * Whether a media type is the one a body is described as by default, and
+ * the framework sends a returned value with. Compared without regard to
+ * case, as media types are.
+ */
+export declare function isJson(type: string): boolean;
+/**
+ * Whether a body under this key is JSON to parse: `application/json`, or
+ * a type with the `+json` suffix. A range is not — its schema describes
+ * the bytes of whatever type answers — and neither is `x-ndjson`, which
+ * is lines of JSON, not one value.
+ */
+export declare function parsesAsJson(type: string): boolean;
+//# sourceMappingURL=media.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/media.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAgB3D;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIlD"}

package/dist/src/operation.d.ts

@@ -17,10 +17,13 @@ import type { Envelopes } from "./envelopes.ts";
 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.
+ * ones the document keeps — whichever operation refers to them first. What
+ * its handler was annotated with is the route's own too, and declares the
+ * same way.
  *
  * Runs before any operation is built. A schema that cannot describe itself
- * is skipped without a word: building the operation says so, once.
+ * is skipped without a word: building the operation says so, once. A body
+ * of another type than JSON is no envelope.
  */
 export declare function declareEnvelopes(entry: RouteTableEntry, envelopes: Envelopes): void;
 /**

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,EAGV,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,CAcN;AA2OD;;;;;;;;;;;;;;;;;;;;;;;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,EAGV,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;AAMhD,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;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,SAAS,GACnB,IAAI,CA8BN;AA+OD;;;;;;;;;;;;;;;;;;;;;;;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/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAErE,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,OAAO,KACV,IAAI,GAAG,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAQf"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAGrE,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,OAAO,KACV,IAAI,GAAG,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/src/testing.js

@@ -1,4 +1,8 @@
 // @bun
+import {
+  parsesAsJson
+} from "../index-f49v8ege.js";
+
 // packages/openapi/src/testing.ts
 async function assertDescribed(document, request, response, options = {}) {
   const problems = await problemsOf(document, request, response, options);
@@ -59,26 +63,38 @@ function templateOf(document, path) {
 function isParameter(segment) {
   return segment.startsWith("{") && segment.endsWith("}");
 }
+function keyFor(described, mediaType) {
+  const [type] = mediaType.split("/");
+  for (const wanted of [mediaType, `${type}/*`, "*/*"]) {
+    const key = described.find((each) => each.toLowerCase() === wanted);
+    if (key !== undefined) {
+      return key;
+    }
+  }
+  return;
+}
 async function bodyProblems(document, status, described, response, options) {
   const text = await response.clone().text();
   const content = described.content ?? {};
   const mediaTypes = Object.keys(content);
+  const mediaType = (response.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+  const key = mediaType === "" ? undefined : keyFor(mediaTypes, mediaType);
   if (text === "") {
-    return mediaTypes.length === 0 ? [] : [
+    const empty = mediaTypes.length === 0 || key !== undefined && !parsesAsJson(key) || mediaType === "" && mediaTypes.some((each) => !parsesAsJson(each));
+    return empty ? [] : [
       `an empty body, where its ${status} describes ${mediaTypes.join(", ")}`
     ];
   }
   if (mediaTypes.length === 0) {
     return [`a body, where its ${status} describes none`];
   }
-  const mediaType = (response.headers.get("content-type") ?? "").split(";")[0]?.trim();
-  if (mediaType === undefined || !mediaTypes.includes(mediaType)) {
+  if (key === undefined) {
     return [
-      `a body of type "${mediaType ?? ""}", where its ${status} describes ${mediaTypes.join(", ")}`
+      `a body of type "${mediaType}", where its ${status} describes ${mediaTypes.join(", ")}`
     ];
   }
-  const schema = content[mediaType]?.schema;
-  if (schema === undefined || !mediaType.endsWith("json")) {
+  const schema = content[key]?.schema;
+  if (schema === undefined || !parsesAsJson(key)) {
     return [];
   }
   let body;
@@ -203,5 +219,5 @@ export {
   assertDescribed
 };
 
-//# debugId=7B8B75FA0C83D4F464756E2164756E21
+//# debugId=CF216AE6A46C36AE64756E2164756E21
 //# sourceMappingURL=testing.js.map

package/dist/src/testing.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/testing.ts"],
   "sourcesContent": [
-    "/**\n * Checking a response against the document, in a test.\n *\n * The document describes what every operation can answer; a test provokes\n * one answer. `assertDescribed` holds the two together: the status is\n * declared, the body is one the status describes, a header asked about is\n * documented. What it catches is what a client generated from the document\n * would trip over — an error code nobody declared, a field the schema says\n * is always there and is not.\n *\n * It checks only what a test provoked, which is why it can be strict: the\n * core does not compare a thrown error with the route's response map,\n * because a guard's refusal would be reported on every route it runs on;\n * a test that provoked the refusal asks about that one response.\n *\n * ```ts\n * import { assertDescribed } from \"@tetsujs/openapi/testing\";\n *\n * const { document } = openapi(app, { info });\n *\n * test(\"a wrong code is what the document says\", async () => {\n *   const res = await request(\"/session\", { method: \"POST\", body });\n *\n *   await assertDescribed(document, \"POST /session\", res);\n * });\n * ```\n *\n * @module\n */\n\nimport type { OpenApiDocument, ResponseObject } from \"./document.ts\";\n\n/** What `assertDescribed` checks besides the status and the body's shape. */\nexport interface AssertDescribedOptions {\n  /**\n   * Checks the body against its schema in full, with the JSON Schema\n   * validator of your choice — this package has none, and without one\n   * only the top level is compared: required fields, fields that are a\n   * `const`. Return `true` when the body is valid, or what is wrong.\n   *\n   * The schema stands on its own: every `$ref` into the document's\n   * components points into its own `$defs`.\n   *\n   * @example\n   * ```ts\n   * const ajv = new Ajv2020();\n   *\n   * await assertDescribed(document, \"POST /session\", res, {\n   *   validate: (schema, body) => ajv.validate(schema, body) || ajv.errorsText(),\n   * });\n   * ```\n   */\n  readonly validate?: (\n    schema: Record<string, unknown>,\n    body: unknown,\n  ) => true | string;\n\n  /**\n   * Headers the status must declare when the response carries them —\n   * `retry-after`. Only those named: a response carries headers no\n   * document describes, `content-type` and `x-request-id` among them.\n   *\n   * The other way needs no list: a header the status declares required —\n   * a `location`, a `set-cookie` — is one the response must carry.\n   */\n  readonly headers?: readonly string[];\n}\n\n/**\n * Throws unless the response is one the document describes for the\n * operation, listing every way it is not.\n *\n * `request` names the operation as the test called it — a method and the\n * path it requested, `\"GET /users/42\"` — matched against the document's\n * path templates. The body is read from a clone, and the test can still\n * read the response.\n */\nexport async function assertDescribed(\n  document: OpenApiDocument,\n  request: string,\n  response: Response,\n  options: AssertDescribedOptions = {},\n): Promise<void> {\n  const problems = await problemsOf(document, request, response, options);\n\n  if (problems.length > 0) {\n    throw new Error(\n      `${request} answered ${response.status}, which the document does not describe:\\n${problems.map((problem) => `- ${problem}`).join(\"\\n\")}`,\n    );\n  }\n}\n\nasync function problemsOf(\n  document: OpenApiDocument,\n  request: string,\n  response: Response,\n  options: AssertDescribedOptions,\n): Promise<string[]> {\n  const [method = \"\", target = \"\"] = request.split(\" \");\n  const path = target.split(\"?\")[0] ?? \"\";\n  const template = templateOf(document, path);\n  const operation =\n    template === undefined\n      ? undefined\n      : document.paths[template]?.[method.toLowerCase()];\n\n  if (operation === undefined) {\n    return [`there is no operation for ${method.toUpperCase()} ${path}`];\n  }\n\n  const status = String(response.status);\n  const described = operation.responses[status];\n\n  if (described === undefined) {\n    return [\n      `${status}, which the operation does not declare: it declares ${Object.keys(operation.responses).join(\", \")}`,\n    ];\n  }\n\n  return [\n    ...(await bodyProblems(document, status, described, response, options)),\n    ...headerProblems(status, described, response, options.headers ?? []),\n  ];\n}\n\n/**\n * The path template a requested path belongs to: the one whose segments\n * match it, `{param}` matching any one segment. Of several, the one with\n * the most literal segments, as the router prefers `/users/me` to\n * `/users/{id}`. A template ending in `{wildcard}` — the name the\n * generator gives a trailing `*` — matches the rest of the path; any other\n * matches as many segments as it has, so a mistyped path is no operation\n * rather than the one it happens to start like.\n */\nfunction templateOf(\n  document: OpenApiDocument,\n  path: string,\n): string | undefined {\n  const segments = path.split(\"/\").filter(Boolean);\n\n  let best: { template: string; literals: number } | undefined;\n\n  for (const template of Object.keys(document.paths)) {\n    const parts = template.split(\"/\").filter(Boolean);\n    const last = parts.at(-1) ?? \"\";\n    const rest = last === \"{wildcard}\" && segments.length > parts.length;\n\n    if (parts.length !== segments.length && !rest) {\n      continue;\n    }\n\n    let literals = 0;\n    let matches = true;\n\n    for (const [index, part] of parts.entries()) {\n      if (isParameter(part)) {\n        continue;\n      }\n\n      if (part !== segments[index]) {\n        matches = false;\n\n        break;\n      }\n\n      literals += 1;\n    }\n\n    if (matches && (best === undefined || literals > best.literals)) {\n      best = { template, literals };\n    }\n  }\n\n  return best?.template;\n}\n\nfunction isParameter(segment: string): boolean {\n  return segment.startsWith(\"{\") && segment.endsWith(\"}\");\n}\n\nasync function bodyProblems(\n  document: OpenApiDocument,\n  status: string,\n  described: ResponseObject,\n  response: Response,\n  options: AssertDescribedOptions,\n): Promise<string[]> {\n  const text = await response.clone().text();\n  const content = described.content ?? {};\n  const mediaTypes = Object.keys(content);\n\n  if (text === \"\") {\n    return mediaTypes.length === 0\n      ? []\n      : [\n          `an empty body, where its ${status} describes ${mediaTypes.join(\", \")}`,\n        ];\n  }\n\n  if (mediaTypes.length === 0) {\n    return [`a body, where its ${status} describes none`];\n  }\n\n  const mediaType = (response.headers.get(\"content-type\") ?? \"\")\n    .split(\";\")[0]\n    ?.trim();\n\n  if (mediaType === undefined || !mediaTypes.includes(mediaType)) {\n    return [\n      `a body of type \"${mediaType ?? \"\"}\", where its ${status} describes ${mediaTypes.join(\", \")}`,\n    ];\n  }\n\n  const schema = content[mediaType]?.schema;\n\n  if (schema === undefined || !mediaType.endsWith(\"json\")) {\n    return [];\n  }\n\n  let body: unknown;\n\n  try {\n    body = JSON.parse(text);\n  } catch {\n    return [`a body that is not the JSON its ${status} describes`];\n  }\n\n  const problems = shapeProblems(document, status, schema, body);\n\n  if (options.validate) {\n    const verdict = options.validate(standalone(document, schema), body);\n\n    if (verdict !== true) {\n      problems.push(verdict);\n    }\n  }\n\n  return problems;\n}\n\n/**\n * What the top level of a body gets wrong against every alternative its\n * status describes — nothing, when one of them fits. Named by the field\n * that tells the alternatives apart, when they have one: the code of an\n * envelope, compared with the codes the status lists.\n */\nfunction shapeProblems(\n  document: OpenApiDocument,\n  status: string,\n  schema: Record<string, unknown>,\n  body: unknown,\n): string[] {\n  const alternatives = alternativesOf(document, schema);\n  const misfits = alternatives.map((alternative) =>\n    misfitOf(alternative, body),\n  );\n\n  if (misfits.some((misfit) => misfit === undefined)) {\n    return [];\n  }\n\n  const field = tellingField(alternatives);\n\n  if (field !== undefined && isRecord(body) && field in body) {\n    const listed: unknown[] = alternatives\n      .map((alternative) => constOf(propertiesOf(alternative)[field]))\n      .filter((value) => value !== undefined);\n\n    if (!listed.includes(body[field])) {\n      return [\n        `${field} ${JSON.stringify(body[field])}, which its ${status} does not list: ${listed.map(String).join(\", \")}`,\n      ];\n    }\n  }\n\n  const reasons = [...new Set(misfits)];\n\n  return [\n    reasons.length === 1\n      ? `a body that ${reasons[0]}`\n      : `a body that fits none of the ${alternatives.length} its ${status} describes: ${reasons.join(\"; \")}`,\n  ];\n}\n\n/** The alternatives a schema stands for, each `$ref` followed. */\nfunction alternativesOf(\n  document: OpenApiDocument,\n  schema: SchemaView,\n): SchemaView[] {\n  const resolved = resolve(document, schema);\n  const union = resolved.anyOf ?? resolved.oneOf;\n\n  if (Array.isArray(union)) {\n    return union.flatMap((branch) =>\n      isRecord(branch) ? alternativesOf(document, branch) : [],\n    );\n  }\n\n  return [resolved];\n}\n\nfunction resolve(document: OpenApiDocument, schema: SchemaView): SchemaView {\n  const ref = schema.$ref;\n\n  if (typeof ref !== \"string\" || !ref.startsWith(\"#/components/schemas/\")) {\n    return schema;\n  }\n\n  const target =\n    document.components?.schemas?.[ref.slice(\"#/components/schemas/\".length)];\n\n  return isRecord(target) ? target : schema;\n}\n\n/**\n * How a body fails one alternative at the top level, or `undefined` when\n * it does not: a required field missing, a `const` field different.\n */\nfunction misfitOf(alternative: SchemaView, body: unknown): string | undefined {\n  const properties = propertiesOf(alternative);\n  const required = Array.isArray(alternative.required)\n    ? (alternative.required as string[])\n    : [];\n\n  if (alternative.type === \"object\" || required.length > 0) {\n    if (!isRecord(body)) {\n      return \"is not an object\";\n    }\n\n    const missing = required.filter((name) => !(name in body));\n\n    if (missing.length > 0) {\n      return `lacks ${missing.join(\", \")}`;\n    }\n\n    for (const [name, property] of Object.entries(properties)) {\n      const expected = constOf(property);\n\n      if (expected !== undefined && name in body && body[name] !== expected) {\n        return `has ${name} ${JSON.stringify(body[name])} where it is ${JSON.stringify(expected)}`;\n      }\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * The field whose `const` differs from one alternative to the next — the\n * code of an envelope — or none.\n */\nfunction tellingField(alternatives: readonly SchemaView[]): string | undefined {\n  const [first] = alternatives;\n\n  if (first === undefined) {\n    return undefined;\n  }\n\n  return Object.keys(propertiesOf(first)).find(\n    (name) =>\n      name !== \"status\" &&\n      alternatives.every(\n        (alternative) =>\n          typeof constOf(propertiesOf(alternative)[name]) === \"string\",\n      ),\n  );\n}\n\nfunction propertiesOf(schema: SchemaView): Record<string, unknown> {\n  return isRecord(schema.properties) ? schema.properties : {};\n}\n\nfunction constOf(value: unknown): unknown {\n  if (!isRecord(value)) {\n    return undefined;\n  }\n\n  const property: SchemaView = value;\n\n  if (\"const\" in property) {\n    return property.const;\n  }\n\n  return Array.isArray(property.enum) && property.enum.length === 1\n    ? property.enum[0]\n    : undefined;\n}\n\n/**\n * A schema that needs nothing but itself: the document's components as its\n * `$defs`, and every reference into them pointed there — what a validator\n * that knows JSON Schema and not OpenAPI can compile.\n */\nfunction standalone(\n  document: OpenApiDocument,\n  schema: Record<string, unknown>,\n): Record<string, unknown> {\n  const repoint = (value: unknown): unknown => {\n    if (Array.isArray(value)) {\n      return value.map(repoint);\n    }\n\n    if (!isRecord(value)) {\n      return value;\n    }\n\n    return Object.fromEntries(\n      Object.entries(value).map(([key, inner]) => [\n        key,\n        key === \"$ref\" && typeof inner === \"string\"\n          ? inner.replace(\"#/components/schemas/\", \"#/$defs/\")\n          : repoint(inner),\n      ]),\n    );\n  };\n\n  return {\n    ...(repoint(schema) as Record<string, unknown>),\n    $defs: repoint(document.components?.schemas ?? {}),\n  };\n}\n\nfunction headerProblems(\n  status: string,\n  described: ResponseObject,\n  response: Response,\n  names: readonly string[],\n): string[] {\n  const declared = Object.keys(described.headers ?? {}).map((name) =>\n    name.toLowerCase(),\n  );\n\n  const undeclared = names\n    .filter(\n      (name) =>\n        response.headers.has(name) && !declared.includes(name.toLowerCase()),\n    )\n    .map(\n      (name) => `the header \"${name}\", which its ${status} does not declare`,\n    );\n\n  const missing = Object.entries(described.headers ?? {})\n    .filter(([name, header]) => header.required && !response.headers.has(name))\n    .map(([name]) => `no header \"${name}\", which its ${status} requires`);\n\n  return [...undeclared, ...missing];\n}\n\n/**\n * A schema as this module reads it: any keyword, with the ones it looks\n * into named, so reading them does not depend on the reader's\n * `noPropertyAccessFromIndexSignature`.\n */\ninterface SchemaView {\n  readonly $ref?: unknown;\n  readonly anyOf?: unknown;\n  readonly oneOf?: unknown;\n  readonly type?: unknown;\n  readonly required?: unknown;\n  readonly properties?: unknown;\n  readonly const?: unknown;\n  readonly enum?: unknown;\n  readonly [keyword: string]: unknown;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n"
+    "/**\n * Checking a response against the document, in a test.\n *\n * The document describes what every operation can answer; a test provokes\n * one answer. `assertDescribed` holds the two together: the status is\n * declared, the body is one the status describes, a header asked about is\n * documented. What it catches is what a client generated from the document\n * would trip over — an error code nobody declared, a field the schema says\n * is always there and is not.\n *\n * It checks only what a test provoked, which is why it can be strict: the\n * core does not compare a thrown error with the route's response map,\n * because a guard's refusal would be reported on every route it runs on;\n * a test that provoked the refusal asks about that one response.\n *\n * ```ts\n * import { assertDescribed } from \"@tetsujs/openapi/testing\";\n *\n * const { document } = openapi(app, { info });\n *\n * test(\"a wrong code is what the document says\", async () => {\n *   const res = await request(\"/session\", { method: \"POST\", body });\n *\n *   await assertDescribed(document, \"POST /session\", res);\n * });\n * ```\n *\n * @module\n */\n\nimport type { OpenApiDocument, ResponseObject } from \"./document.ts\";\nimport { parsesAsJson } from \"./media.ts\";\n\n/** What `assertDescribed` checks besides the status and the body's shape. */\nexport interface AssertDescribedOptions {\n  /**\n   * Checks the body against its schema in full, with the JSON Schema\n   * validator of your choice — this package has none, and without one\n   * only the top level is compared: required fields, fields that are a\n   * `const`. Return `true` when the body is valid, or what is wrong.\n   *\n   * The schema stands on its own: every `$ref` into the document's\n   * components points into its own `$defs`.\n   *\n   * @example\n   * ```ts\n   * const ajv = new Ajv2020();\n   *\n   * await assertDescribed(document, \"POST /session\", res, {\n   *   validate: (schema, body) => ajv.validate(schema, body) || ajv.errorsText(),\n   * });\n   * ```\n   */\n  readonly validate?: (\n    schema: Record<string, unknown>,\n    body: unknown,\n  ) => true | string;\n\n  /**\n   * Headers the status must declare when the response carries them —\n   * `retry-after`. Only those named: a response carries headers no\n   * document describes, `content-type` and `x-request-id` among them.\n   *\n   * The other way needs no list: a header the status declares required —\n   * a `location`, a `set-cookie` — is one the response must carry.\n   */\n  readonly headers?: readonly string[];\n}\n\n/**\n * Throws unless the response is one the document describes for the\n * operation, listing every way it is not.\n *\n * `request` names the operation as the test called it — a method and the\n * path it requested, `\"GET /users/42\"` — matched against the document's\n * path templates. The body is read from a clone, and the test can still\n * read the response.\n */\nexport async function assertDescribed(\n  document: OpenApiDocument,\n  request: string,\n  response: Response,\n  options: AssertDescribedOptions = {},\n): Promise<void> {\n  const problems = await problemsOf(document, request, response, options);\n\n  if (problems.length > 0) {\n    throw new Error(\n      `${request} answered ${response.status}, which the document does not describe:\\n${problems.map((problem) => `- ${problem}`).join(\"\\n\")}`,\n    );\n  }\n}\n\nasync function problemsOf(\n  document: OpenApiDocument,\n  request: string,\n  response: Response,\n  options: AssertDescribedOptions,\n): Promise<string[]> {\n  const [method = \"\", target = \"\"] = request.split(\" \");\n  const path = target.split(\"?\")[0] ?? \"\";\n  const template = templateOf(document, path);\n  const operation =\n    template === undefined\n      ? undefined\n      : document.paths[template]?.[method.toLowerCase()];\n\n  if (operation === undefined) {\n    return [`there is no operation for ${method.toUpperCase()} ${path}`];\n  }\n\n  const status = String(response.status);\n  const described = operation.responses[status];\n\n  if (described === undefined) {\n    return [\n      `${status}, which the operation does not declare: it declares ${Object.keys(operation.responses).join(\", \")}`,\n    ];\n  }\n\n  return [\n    ...(await bodyProblems(document, status, described, response, options)),\n    ...headerProblems(status, described, response, options.headers ?? []),\n  ];\n}\n\n/**\n * The path template a requested path belongs to: the one whose segments\n * match it, `{param}` matching any one segment. Of several, the one with\n * the most literal segments, as the router prefers `/users/me` to\n * `/users/{id}`. A template ending in `{wildcard}` — the name the\n * generator gives a trailing `*` — matches the rest of the path; any other\n * matches as many segments as it has, so a mistyped path is no operation\n * rather than the one it happens to start like.\n */\nfunction templateOf(\n  document: OpenApiDocument,\n  path: string,\n): string | undefined {\n  const segments = path.split(\"/\").filter(Boolean);\n\n  let best: { template: string; literals: number } | undefined;\n\n  for (const template of Object.keys(document.paths)) {\n    const parts = template.split(\"/\").filter(Boolean);\n    const last = parts.at(-1) ?? \"\";\n    const rest = last === \"{wildcard}\" && segments.length > parts.length;\n\n    if (parts.length !== segments.length && !rest) {\n      continue;\n    }\n\n    let literals = 0;\n    let matches = true;\n\n    for (const [index, part] of parts.entries()) {\n      if (isParameter(part)) {\n        continue;\n      }\n\n      if (part !== segments[index]) {\n        matches = false;\n\n        break;\n      }\n\n      literals += 1;\n    }\n\n    if (matches && (best === undefined || literals > best.literals)) {\n      best = { template, literals };\n    }\n  }\n\n  return best?.template;\n}\n\nfunction isParameter(segment: string): boolean {\n  return segment.startsWith(\"{\") && segment.endsWith(\"}\");\n}\n\n/**\n * The media type of the document that describes a response's body: its\n * own, then the range of its type, then the range of every type — the\n * order in which OpenAPI lets the more specific one win. Compared without\n * regard to case, as media types are.\n */\nfunction keyFor(\n  described: readonly string[],\n  mediaType: string,\n): string | undefined {\n  const [type] = mediaType.split(\"/\");\n\n  for (const wanted of [mediaType, `${type}/*`, \"*/*\"]) {\n    const key = described.find((each) => each.toLowerCase() === wanted);\n\n    if (key !== undefined) {\n      return key;\n    }\n  }\n\n  return undefined;\n}\n\nasync function bodyProblems(\n  document: OpenApiDocument,\n  status: string,\n  described: ResponseObject,\n  response: Response,\n  options: AssertDescribedOptions,\n): Promise<string[]> {\n  const text = await response.clone().text();\n  const content = described.content ?? {};\n  const mediaTypes = Object.keys(content);\n\n  const mediaType =\n    (response.headers.get(\"content-type\") ?? \"\")\n      .split(\";\")[0]\n      ?.trim()\n      .toLowerCase() ?? \"\";\n\n  const key = mediaType === \"\" ? undefined : keyFor(mediaTypes, mediaType);\n\n  /**\n   * An empty export, a file of no bytes, a stream that yielded nothing:\n   * empty is content of every type but JSON, which has no empty value. An\n   * empty body may carry no type at all, and still be one a status of\n   * another type than JSON describes.\n   */\n  if (text === \"\") {\n    const empty =\n      mediaTypes.length === 0 ||\n      (key !== undefined && !parsesAsJson(key)) ||\n      (mediaType === \"\" && mediaTypes.some((each) => !parsesAsJson(each)));\n\n    return empty\n      ? []\n      : [\n          `an empty body, where its ${status} describes ${mediaTypes.join(\", \")}`,\n        ];\n  }\n\n  if (mediaTypes.length === 0) {\n    return [`a body, where its ${status} describes none`];\n  }\n\n  if (key === undefined) {\n    return [\n      `a body of type \"${mediaType}\", where its ${status} describes ${mediaTypes.join(\", \")}`,\n    ];\n  }\n\n  const schema = content[key]?.schema;\n\n  if (schema === undefined || !parsesAsJson(key)) {\n    return [];\n  }\n\n  let body: unknown;\n\n  try {\n    body = JSON.parse(text);\n  } catch {\n    return [`a body that is not the JSON its ${status} describes`];\n  }\n\n  const problems = shapeProblems(document, status, schema, body);\n\n  if (options.validate) {\n    const verdict = options.validate(standalone(document, schema), body);\n\n    if (verdict !== true) {\n      problems.push(verdict);\n    }\n  }\n\n  return problems;\n}\n\n/**\n * What the top level of a body gets wrong against every alternative its\n * status describes — nothing, when one of them fits. Named by the field\n * that tells the alternatives apart, when they have one: the code of an\n * envelope, compared with the codes the status lists.\n */\nfunction shapeProblems(\n  document: OpenApiDocument,\n  status: string,\n  schema: Record<string, unknown>,\n  body: unknown,\n): string[] {\n  const alternatives = alternativesOf(document, schema);\n  const misfits = alternatives.map((alternative) =>\n    misfitOf(alternative, body),\n  );\n\n  if (misfits.some((misfit) => misfit === undefined)) {\n    return [];\n  }\n\n  const field = tellingField(alternatives);\n\n  if (field !== undefined && isRecord(body) && field in body) {\n    const listed: unknown[] = alternatives\n      .map((alternative) => constOf(propertiesOf(alternative)[field]))\n      .filter((value) => value !== undefined);\n\n    if (!listed.includes(body[field])) {\n      return [\n        `${field} ${JSON.stringify(body[field])}, which its ${status} does not list: ${listed.map(String).join(\", \")}`,\n      ];\n    }\n  }\n\n  const reasons = [...new Set(misfits)];\n\n  return [\n    reasons.length === 1\n      ? `a body that ${reasons[0]}`\n      : `a body that fits none of the ${alternatives.length} its ${status} describes: ${reasons.join(\"; \")}`,\n  ];\n}\n\n/** The alternatives a schema stands for, each `$ref` followed. */\nfunction alternativesOf(\n  document: OpenApiDocument,\n  schema: SchemaView,\n): SchemaView[] {\n  const resolved = resolve(document, schema);\n  const union = resolved.anyOf ?? resolved.oneOf;\n\n  if (Array.isArray(union)) {\n    return union.flatMap((branch) =>\n      isRecord(branch) ? alternativesOf(document, branch) : [],\n    );\n  }\n\n  return [resolved];\n}\n\nfunction resolve(document: OpenApiDocument, schema: SchemaView): SchemaView {\n  const ref = schema.$ref;\n\n  if (typeof ref !== \"string\" || !ref.startsWith(\"#/components/schemas/\")) {\n    return schema;\n  }\n\n  const target =\n    document.components?.schemas?.[ref.slice(\"#/components/schemas/\".length)];\n\n  return isRecord(target) ? target : schema;\n}\n\n/**\n * How a body fails one alternative at the top level, or `undefined` when\n * it does not: a required field missing, a `const` field different.\n */\nfunction misfitOf(alternative: SchemaView, body: unknown): string | undefined {\n  const properties = propertiesOf(alternative);\n  const required = Array.isArray(alternative.required)\n    ? (alternative.required as string[])\n    : [];\n\n  if (alternative.type === \"object\" || required.length > 0) {\n    if (!isRecord(body)) {\n      return \"is not an object\";\n    }\n\n    const missing = required.filter((name) => !(name in body));\n\n    if (missing.length > 0) {\n      return `lacks ${missing.join(\", \")}`;\n    }\n\n    for (const [name, property] of Object.entries(properties)) {\n      const expected = constOf(property);\n\n      if (expected !== undefined && name in body && body[name] !== expected) {\n        return `has ${name} ${JSON.stringify(body[name])} where it is ${JSON.stringify(expected)}`;\n      }\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * The field whose `const` differs from one alternative to the next — the\n * code of an envelope — or none.\n */\nfunction tellingField(alternatives: readonly SchemaView[]): string | undefined {\n  const [first] = alternatives;\n\n  if (first === undefined) {\n    return undefined;\n  }\n\n  return Object.keys(propertiesOf(first)).find(\n    (name) =>\n      name !== \"status\" &&\n      alternatives.every(\n        (alternative) =>\n          typeof constOf(propertiesOf(alternative)[name]) === \"string\",\n      ),\n  );\n}\n\nfunction propertiesOf(schema: SchemaView): Record<string, unknown> {\n  return isRecord(schema.properties) ? schema.properties : {};\n}\n\nfunction constOf(value: unknown): unknown {\n  if (!isRecord(value)) {\n    return undefined;\n  }\n\n  const property: SchemaView = value;\n\n  if (\"const\" in property) {\n    return property.const;\n  }\n\n  return Array.isArray(property.enum) && property.enum.length === 1\n    ? property.enum[0]\n    : undefined;\n}\n\n/**\n * A schema that needs nothing but itself: the document's components as its\n * `$defs`, and every reference into them pointed there — what a validator\n * that knows JSON Schema and not OpenAPI can compile.\n */\nfunction standalone(\n  document: OpenApiDocument,\n  schema: Record<string, unknown>,\n): Record<string, unknown> {\n  const repoint = (value: unknown): unknown => {\n    if (Array.isArray(value)) {\n      return value.map(repoint);\n    }\n\n    if (!isRecord(value)) {\n      return value;\n    }\n\n    return Object.fromEntries(\n      Object.entries(value).map(([key, inner]) => [\n        key,\n        key === \"$ref\" && typeof inner === \"string\"\n          ? inner.replace(\"#/components/schemas/\", \"#/$defs/\")\n          : repoint(inner),\n      ]),\n    );\n  };\n\n  return {\n    ...(repoint(schema) as Record<string, unknown>),\n    $defs: repoint(document.components?.schemas ?? {}),\n  };\n}\n\nfunction headerProblems(\n  status: string,\n  described: ResponseObject,\n  response: Response,\n  names: readonly string[],\n): string[] {\n  const declared = Object.keys(described.headers ?? {}).map((name) =>\n    name.toLowerCase(),\n  );\n\n  const undeclared = names\n    .filter(\n      (name) =>\n        response.headers.has(name) && !declared.includes(name.toLowerCase()),\n    )\n    .map(\n      (name) => `the header \"${name}\", which its ${status} does not declare`,\n    );\n\n  const missing = Object.entries(described.headers ?? {})\n    .filter(([name, header]) => header.required && !response.headers.has(name))\n    .map(([name]) => `no header \"${name}\", which its ${status} requires`);\n\n  return [...undeclared, ...missing];\n}\n\n/**\n * A schema as this module reads it: any keyword, with the ones it looks\n * into named, so reading them does not depend on the reader's\n * `noPropertyAccessFromIndexSignature`.\n */\ninterface SchemaView {\n  readonly $ref?: unknown;\n  readonly anyOf?: unknown;\n  readonly oneOf?: unknown;\n  readonly type?: unknown;\n  readonly required?: unknown;\n  readonly properties?: unknown;\n  readonly const?: unknown;\n  readonly enum?: unknown;\n  readonly [keyword: string]: unknown;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "7B8B75FA0C83D4F464756E2164756E21",
+  "mappings": "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",
+  "debugId": "CF216AE6A46C36AE64756E2164756E21",
   "names": []
 }

package/package.json

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

package/src/annotations.ts

@@ -1,12 +1,14 @@
 /**
- * What hooks contribute to the documentation.
+ * What hooks, and the handlers packages hand out, contribute to the
+ * documentation.
  *
  * What a route is protected by, or answers with when a guard refuses, is
  * not in its config: a hook is a function in a slot, and the route that
  * mounts it says nothing about tokens or rate limits. The contribution is
  * therefore annotated onto the hook — from this package, not from
  * `hook.*` — so the core keeps knowing nothing about OpenAPI and the
- * factories stay free of documentation options.
+ * factories stay free of documentation options. A package's handler is
+ * annotated the same way, for the routes that mount it.
  *
  * A hook annotated once is documented everywhere it runs: application and
  * group chains are merged into every route's chains at startup, so a guard
@@ -18,6 +20,7 @@
 
 import type { AnyHook, AnySchema } from "@tetsujs/core";
 import type { JsonSchema } from "./json-schema.ts";
+import { isMediaType } from "./media.ts";
 
 /**
  * The definition of a scheme, as OpenAPI spells it.
@@ -63,15 +66,37 @@ export interface SecurityRequirement {
 
 /**
  * One response a hook can produce, which the route's own schema knows
- * nothing about — a rate limiter's `429`, a guard's `401`.
+ * nothing about — a rate limiter's `429`, a guard's `401` — or one a
+ * package's handler answers with, for the routes that mount it: a file,
+ * a `304`.
  */
 export interface DocumentedResponse {
   readonly status: number;
   readonly description: string;
 
-  /** The body, when the hook answers with one. */
+  /**
+   * The body, when it is described: JSON, or the content under
+   * `contentType` when there is one.
+   *
+   * Without `schema` or `contentType`, an error status — `400` and above —
+   * answers with the framework's envelope, which `error`, `message` and
+   * `fields` describe, and any other status carries no body: a `304`, a
+   * redirect.
+   */
   readonly schema?: AnySchema;
 
+  /**
+   * The media type of the body when it is not JSON — `"text/html"`, or a
+   * range such as `"image/*"` or the range of every type for a file whose
+   * type is not known in advance. Without a `schema`, the body is
+   * described by its type alone.
+   *
+   * Two responses of one status with different types are both in the
+   * document, each under its own: the site's `404.html` next to the
+   * envelope an API client gets.
+   */
+  readonly contentType?: string;
+
   /**
    * The `error` code of the failure envelope, when the hook answers with
    * the framework's shape — `"RATE_LIMITED"`, `"SESSION_EXPIRED"`.
@@ -153,17 +178,65 @@ export interface HookDocs {
   readonly responses?: readonly DocumentedResponse[];
 }
 
+/**
+ * Everything a handler tells the generator about the route it answers
+ * for.
+ *
+ * A handler a package hands out — a directory of files, say — knows what
+ * it answers with better than the route it is mounted on, whose author
+ * wrote one line: annotated once, it describes every route that mounts it.
+ */
+export interface HandlerDocs {
+  /**
+   * Keeps the route out of the document unless the route says
+   * `docs: { hidden: false }`.
+   *
+   * For a handler whose routes are rarely anyone's API — the files of a
+   * site — and which a generated client could not call anyway. The route's
+   * own word wins either way: `docs: { hidden: true }` hides it whatever
+   * the handler says.
+   */
+  readonly hidden?: boolean;
+
+  /**
+   * What the handler answers with, as the route's own responses: a status
+   * the route's response map declares too is described by both, and a
+   * route that says nothing gets no placeholder `200` in their place.
+   */
+  readonly responses?: readonly DocumentedResponse[];
+}
+
+/** Any handler a route can take; the context is the route's to type. */
+type AnyHandler = (ctx: never) => unknown;
+
 const docsKey = "~tetsu/hook-docs";
+const handlerDocsKey = "~tetsu/handler-docs";
 
 /**
- * Annotates a hook with what it contributes to the documentation.
+ * Annotates a hook, or a handler, with what it contributes to the
+ * documentation.
  *
  * Returns a copy: what the caller exports is what carries the annotation,
- * and a hook used elsewhere is not changed behind its author's back. The
- * type is preserved exactly, so an annotated hook goes into a stack like
- * any other.
+ * and a hook or a handler used elsewhere is not changed behind its
+ * author's back. A handler's copy calls the handler it was made from. The
+ * type is preserved exactly, so an annotated hook goes into a stack, and an
+ * annotated handler onto a route, like any other.
  *
- * @example
+ * Annotating a handler is for one whose type is already settled — a
+ * package's, typed by its own context. An arrow written inside
+ * `documented()` on a route does not get the route's context, which
+ * `route()` would have given it, and does not compile; its statuses belong
+ * in the route's response map.
+ *
+ * One signature, for a hook and a handler alike, and one shape of what is
+ * said about either. An overload for each would keep `hidden` off a hook
+ * and `security` off a handler in the types, but TypeScript before 7
+ * reports a call no overload matches on the whole call, and a misspelled
+ * keyword deep in a response would no longer be pointed at. Those two are
+ * refused here instead, when `documented()` is called — as a module loads,
+ * before anything is served.
+ *
+ * @example A hook
  * ```ts
  * export const limiter = documented(hook.beforeParse(check), {
  *   responses: [
@@ -171,8 +244,60 @@ const docsKey = "~tetsu/hook-docs";
  *   ],
  * });
  * ```
+ *
+ * @example A package's handler, out of the document until a route asks
+ * ```ts
+ * return documented(serveFile, {
+ *   hidden: true,
+ *   responses: [
+ *     { status: 200, description: "The file", contentType: "image/*" },
+ *     { status: 304, description: "Not modified" },
+ *   ],
+ * });
+ * ```
  */
-export function documented<H extends AnyHook>(hook: H, docs: HookDocs): H {
+export function documented<T extends AnyHook | AnyHandler>(
+  target: T,
+  docs: HookDocs & HandlerDocs,
+): T {
+  const handled = typeof target === "function";
+
+  if (handled && docs.security !== undefined) {
+    throw new Error(
+      "documented() was given security for a handler — security is stated on the hook that enforces it, with secured()",
+    );
+  }
+
+  if (!handled && docs.hidden !== undefined) {
+    throw new Error(
+      "documented() was given hidden for a hook — a route is hidden by its own docs, or by its handler's annotation, not by a hook it mounts",
+    );
+  }
+
+  for (const response of docs.responses ?? []) {
+    if (
+      response.contentType !== undefined &&
+      !isMediaType(response.contentType)
+    ) {
+      throw new Error(
+        `The ${response.status} response given to documented() has the content type ${JSON.stringify(response.contentType)}, which is not a type such as text/html or a range such as image/* — the type alone, without parameters: the charset belongs on the response`,
+      );
+    }
+  }
+
+  if (handled) {
+    const handler = target as AnyHandler;
+    const copy: AnyHandler = (ctx) => handler(ctx);
+
+    Object.defineProperty(copy, handlerDocsKey, {
+      enumerable: false,
+      value: { ...handlerDocsOf(handler), ...docs },
+    });
+
+    return copy as T;
+  }
+
+  const hook = target as AnyHook;
   const annotated = { ...hook };
 
   Object.defineProperty(annotated, docsKey, {
@@ -180,7 +305,7 @@ export function documented<H extends AnyHook>(hook: H, docs: HookDocs): H {
     value: { ...docsOf(hook), ...docs },
   });
 
-  return annotated as H;
+  return annotated as T;
 }
 
 /**
@@ -230,6 +355,15 @@ export function docsOf(hook: AnyHook): HookDocs | undefined {
   return (hook as unknown as Record<string, HookDocs | undefined>)[docsKey];
 }
 
+/** Reads everything a handler was annotated with. */
+export function handlerDocsOf(handler: unknown): HandlerDocs | undefined {
+  return typeof handler === "function"
+    ? (handler as unknown as Record<string, HandlerDocs | undefined>)[
+        handlerDocsKey
+      ]
+    : undefined;
+}
+
 /** Reads the security a hook was annotated with, if it was. */
 export function securityOf(
   hook: AnyHook,
@@ -258,11 +392,12 @@ export interface HookContributions {
 /**
  * Collects the contributions of a route's chains.
  *
- * A scheme is registered once per name and a response once per status and
- * description: the same guard on the application and on a group is one
- * requirement, not two. Two hooks of one scheme asking for different
- * scopes both run, so the requirement asks for the scopes of both — each
- * once, in the order they were first asked for.
+ * A scheme is registered once per name: two hooks of one scheme asking for
+ * different scopes both run, so the requirement asks for the scopes of
+ * both — each once, in the order they were first asked for. Responses are
+ * kept as the hooks give them. Two guards may answer one status with one
+ * description and different codes, and both are what the route sends;
+ * answers that say the same are folded when the document is written.
  *
  * Deduplicating by name means two hooks claiming one name with different
  * schemes lose one of them, and that is not a duplicate being collapsed —
@@ -275,7 +410,7 @@ export function contributionsOf(
 ): HookContributions {
   const security = new Map<string, SecurityRequirement>();
   const conditions = new Map<string, readonly SecurityRequirement[]>();
-  const responses = new Map<string, DocumentedResponse>();
+  const responses: DocumentedResponse[] = [];
 
   for (const slot of Object.values(chains)) {
     for (const hook of slot) {
@@ -311,20 +446,14 @@ export function contributionsOf(
         }
       }
 
-      for (const response of docs.responses ?? []) {
-        const key = `${response.status} ${response.description}`;
-
-        if (!responses.has(key)) {
-          responses.set(key, response);
-        }
-      }
+      responses.push(...(docs.responses ?? []));
     }
   }
 
   return {
     security: [...security.values()],
     conditions: [...conditions.values()],
-    responses: [...responses.values()],
+    responses,
   };
 }
 

package/src/envelopes.ts

@@ -1,9 +1,10 @@
 /**
  * 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 —
+ * An envelope reaches a document from five directions: a route's response
+ * map, its handler's annotation, 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
@@ -14,11 +15,12 @@
  * 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.
+ * The route's definition wins, its handler's annotation counting as the
+ * route's own. 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.
  *
  * What an envelope looks like — how one is described, where its code is,
  * what a client discriminates on — is the document's error format, which

package/src/index.ts

@@ -19,8 +19,8 @@
  * @module
  */
 
-import type { App } from "@tetsujs/core";
-import { contributionsOf } from "./annotations.ts";
+import type { App, RouteTableEntry } from "@tetsujs/core";
+import { contributionsOf, handlerDocsOf } from "./annotations.ts";
 import { schemaComponents } from "./components.ts";
 import type { OpenApiDocument, PathItemObject, TagObject } from "./document.ts";
 import { envelopes as envelopeDefinitions } from "./envelopes.ts";
@@ -33,6 +33,7 @@ import { unresolvedRefs } from "./refs.ts";
 export type {
   DocumentedHeader,
   DocumentedResponse,
+  HandlerDocs,
   HookContributions,
   HookDocs,
   SecurityAlternatives,
@@ -157,7 +158,9 @@ export interface GeneratorResult {
  *
  * 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.
+ * requires has nothing left to describe. A route that says nothing either
+ * way is hidden when its handler was annotated so — see {@link documented}
+ * — and `docs: { hidden: false }` shows it all the same.
  *
  * Every route of the table becomes an operation under its path template,
  * with the parameters, body and responses its schemas describe. What the
@@ -175,9 +178,7 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
     resolveFormat(options.errors),
   );
   const ids = operationIds();
-  const described = app.entries.filter(
-    (entry) => !entry.ws && !entry.def.docs?.hidden,
-  );
+  const described = app.entries.filter((entry) => !entry.ws && !hidden(entry));
 
   for (const entry of described) {
     declareEnvelopes(entry, envelopes);
@@ -274,6 +275,16 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
   return { document, warnings };
 }
 
+/**
+ * Whether a route stays out of the document: by its own word when it said
+ * one, `true` or `false`, and by its handler's when it said nothing.
+ */
+function hidden(entry: RouteTableEntry): boolean {
+  return (
+    entry.def.docs?.hidden ?? handlerDocsOf(entry.def.handler)?.hidden ?? false
+  );
+}
+
 /**
  * Reports each reference in the document that resolves to nothing: in an
  * operation, at the route it describes; in a definition of