@tetsujs/openapi 0.4.0 → 0.4.2

package/dist/src/index.js

@@ -17,6 +17,7 @@ function docsOf(hook) {
 }
 function contributionsOf(chains, warn) {
   const security = new Map;
+  const conditions = new Map;
   const responses = new Map;
   for (const slot of Object.values(chains)) {
     for (const hook of slot) {
@@ -25,11 +26,20 @@ function contributionsOf(chains, warn) {
         continue;
       }
       if (docs.security) {
-        const claimed = security.get(docs.security.name);
-        if (!claimed) {
-          security.set(docs.security.name, docs.security);
-        } else if (JSON.stringify(claimed.scheme) !== JSON.stringify(docs.security.scheme)) {
-          warn?.(`two hooks claim the security scheme "${docs.security.name}" with different definitions; one of them is not described`);
+        const alternatives = alternativesOf(docs.security);
+        conditions.set(conditionKey(alternatives), alternatives);
+        for (const requirement of alternatives) {
+          const claimed = security.get(requirement.name);
+          if (!claimed) {
+            security.set(requirement.name, requirement);
+          } else if (JSON.stringify(claimed.scheme) === JSON.stringify(requirement.scheme)) {
+            security.set(requirement.name, {
+              ...claimed,
+              scopes: joinScopes(claimed.scopes, requirement.scopes)
+            });
+          } else {
+            warn?.(`two hooks claim the security scheme "${requirement.name}" with different definitions; one of them is not described`);
+          }
         }
       }
       for (const response of docs.responses ?? []) {
@@ -42,9 +52,28 @@ function contributionsOf(chains, warn) {
   }
   return {
     security: [...security.values()],
+    conditions: [...conditions.values()],
     responses: [...responses.values()]
   };
 }
+function alternativesOf(security) {
+  return "anyOf" in security ? security.anyOf : [security];
+}
+function conditionKey(alternatives) {
+  return JSON.stringify(alternatives.map((requirement) => [
+    requirement.name,
+    [...requirement.scopes ?? []].sort()
+  ]));
+}
+function joinScopes(first, second) {
+  const joined = [...first ?? []];
+  for (const scope of second ?? []) {
+    if (!joined.includes(scope)) {
+      joined.push(scope);
+    }
+  }
+  return joined;
+}
 
 // packages/openapi/src/components.ts
 function schemaComponents() {
@@ -73,6 +102,104 @@ function failureName(status, error) {
   return name || `Failure${status}`;
 }
 
+// packages/openapi/src/envelopes.ts
+function envelopes(components) {
+  const declared = new Map;
+  const defined = new Map;
+  const refs = new Map;
+  const codes = new Map;
+  const names = new Map;
+  const reported = new Set;
+  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);
+    }
+  };
+  function nameOf(status, code) {
+    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}`;
+  }
+}
+function envelopeCode(schema) {
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  if (!required.includes("error")) {
+    return;
+  }
+  const error = schema.properties?.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;
+}
+function branchesOf(schema) {
+  const keys = Object.keys(schema);
+  if (keys.length !== 1) {
+    return [schema];
+  }
+  if (Array.isArray(schema.anyOf)) {
+    return schema.anyOf.flatMap(branchesOf);
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const branches = schema.oneOf.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, code) {
+  return `${status} ${code}`;
+}
+function differenceOf(kept, other) {
+  const fields = (schema) => Object.keys(schema.properties ?? {});
+  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) => JSON.stringify([...Array.isArray(schema.required) ? schema.required : []].sort());
+  return required(kept) === required(other) ? undefined : "which fields are required";
+}
+
+// packages/openapi/src/operation.ts
+import { errorBody } from "@tetsujs/core";
+
 // packages/openapi/src/emit.ts
 import { toJsonSchema } from "@tetsujs/core";
 var target = { target: "draft-2020-12" };
@@ -163,7 +290,7 @@ function objectProperties(schema, where, warn) {
 }
 
 // packages/openapi/src/operation.ts
-function operationOf(entry, options, components, ids, warn) {
+function operationOf(entry, options, components, envelopes, ids, warn) {
   const schema = entry.def.schema;
   const parameters = [
     ...pathParameters(entry.path, schema?.params, warn),
@@ -181,14 +308,64 @@ function operationOf(entry, options, components, ids, warn) {
     ...entry.def.docs?.deprecated === undefined ? {} : { deprecated: entry.def.docs.deprecated },
     ...parameters.length > 0 ? { parameters } : {},
     ...body ? { requestBody: body } : {},
-    ...contributed.security.length > 0 ? {
-      security: contributed.security.map((requirement) => ({
-        [requirement.name]: requirement.scopes ?? []
-      }))
-    } : {},
-    responses: responses(entry, options, contributed, components, warn)
+    ...contributed.security.length > 0 ? { security: securityOf(contributed.conditions) } : {},
+    responses: responses(entry, options, contributed, components, envelopes, warn)
   };
 }
+function declareEnvelopes(entry, envelopes) {
+  for (const [status, schema] of declaredResponses(entry)) {
+    const described = schema === null ? undefined : emitted(schema, "", () => {});
+    for (const branch of described ? branchesOf(described) : []) {
+      const code = envelopeCode(branch);
+      if (code !== undefined) {
+        envelopes.declare(Number(status), code, branch);
+      }
+    }
+  }
+}
+function declaredResponses(entry) {
+  const response = entry.def.schema?.response;
+  if (!response) {
+    return [];
+  }
+  if ("~standard" in response) {
+    return [["200", response]];
+  }
+  return Object.entries(response);
+}
+function branchesFor(schema, status, envelopes, warn) {
+  return branchesOf(schema).map((branch) => {
+    const code = envelopeCode(branch);
+    return code === undefined ? branch : envelopes.ref(status, code, branch, warn);
+  });
+}
+function securityOf(conditions) {
+  let combinations = [{}];
+  for (const alternatives of conditions) {
+    combinations = combinations.flatMap((combination) => alternatives.map((requirement) => ({
+      ...combination,
+      [requirement.name]: joined(combination[requirement.name], requirement.scopes)
+    })));
+  }
+  const seen = new Set;
+  return combinations.filter((combination) => {
+    const key = JSON.stringify(Object.entries(combination).map(([name, scopes]) => [name, [...scopes].sort()]).sort());
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+function joined(present, added) {
+  const scopes = [...present ?? []];
+  for (const scope of added ?? []) {
+    if (!scopes.includes(scope)) {
+      scopes.push(scope);
+    }
+  }
+  return scopes;
+}
 function operationIds() {
   const taken = new Map;
   return {
@@ -265,94 +442,147 @@ function carriesBinary(root) {
   }
   return false;
 }
-function responses(entry, options, contributed, components, warn) {
-  const declared = {};
-  const response = entry.def.schema?.response;
-  if (response && "~standard" in response) {
-    declared["200"] = jsonResponse(response, "Successful response", warn);
-  } else if (response) {
-    for (const [status, schema] of Object.entries(response)) {
-      declared[status] = schema === null ? { description: describeStatus(status) } : jsonResponse(schema, describeStatus(status), warn);
-    }
+function responses(entry, options, contributed, components, envelopes, warn) {
+  const answers = new Map;
+  const add = (status, answer) => {
+    answers.set(status, [...answers.get(status) ?? [], answer]);
+  };
+  for (const [status, schema] of declaredResponses(entry)) {
+    const described = schema === null ? undefined : emitted(schema, "a response", warn);
+    add(status, {
+      description: describeStatus(status),
+      placeholder: true,
+      schemas: described ? branchesFor(described, Number(status), envelopes, warn) : []
+    });
+  }
+  if (![...answers.keys()].some((status) => status.startsWith("2"))) {
+    add("200", {
+      description: "Successful response",
+      placeholder: true,
+      schemas: []
+    });
   }
-  if (!declared["200"] && !hasSuccess(declared)) {
-    declared["200"] = { description: "Successful response" };
+  for (const [status, answer] of failures(entry, options, contributed, components, envelopes, warn)) {
+    add(String(status), answer);
   }
-  return {
-    ...declared,
-    ...frameworkFailures(entry, options, contributed, declared, components, warn)
-  };
+  const described = {};
+  for (const [status, list] of answers) {
+    described[status] = merge(list, envelopes);
+  }
+  return described;
 }
-function frameworkFailures(entry, options, contributed, declared, components, warn) {
+function failures(entry, options, contributed, components, envelopes, warn) {
   const schema = entry.def.schema;
-  const failures = new Map;
-  const add = (status, failure) => {
-    const key = String(status);
-    failures.set(key, [...failures.get(key) ?? [], failure]);
+  const found = [];
+  const envelopeRef = (status, error, message, fields) => {
+    const described = envelope(status, error, message, fields);
+    const ref = error === undefined ? components.ref(failureName(status), described) : envelopes.ref(status, error, described, warn);
+    return ref;
   };
-  const envelopeRef = (status, error, message) => components.ref(failureName(status, error), envelope(status, error, message));
   if (schema?.params || schema?.query || schema?.headers || schema?.body) {
-    add(options.validationStatus, {
-      description: "Request failed schema validation",
-      schema: components.ref(failureName(options.validationStatus, "VALIDATION_FAILED"), validationFailed(options.validationStatus))
-    });
+    found.push([
+      options.validationStatus,
+      {
+        description: "Request failed schema validation",
+        schemas: [
+          envelopes.ref(options.validationStatus, "VALIDATION_FAILED", validationFailed(options.validationStatus), warn)
+        ]
+      }
+    ]);
   }
   for (const requirement of contributed.security) {
     const status = requirement.status ?? 401;
-    add(status, {
-      description: requirement.description ?? `Request did not satisfy ${requirement.name}`,
-      schema: envelopeRef(status, requirement.error, requirement.message)
-    });
+    found.push([
+      status,
+      {
+        description: requirement.description ?? `Request did not satisfy ${requirement.name}`,
+        schemas: [envelopeRef(status, requirement.error, requirement.message)]
+      }
+    ]);
   }
   for (const response of contributed.responses) {
     const described = response.schema ? emitted(response.schema, "a hook's response", warn) : undefined;
-    add(response.status, {
-      description: response.description,
-      schema: described ?? envelopeRef(response.status, response.error, response.message)
-    });
+    found.push([
+      response.status,
+      {
+        description: response.description,
+        schemas: described ? branchesFor(described, response.status, envelopes, warn) : [
+          envelopeRef(response.status, response.error, response.message, response.fields)
+        ],
+        ...response.headers ? { headers: response.headers } : {}
+      }
+    ]);
   }
   if (schema?.body || entry.def.bodyType) {
     const unparsable = parseFailure(entry.def.bodyType);
     if (unparsable) {
-      add(400, {
-        description: "Body could not be parsed in the declared shape",
-        schema: envelopeRef(400, unparsable.error, unparsable.message)
-      });
+      found.push([
+        400,
+        {
+          description: "Body could not be parsed in the declared shape",
+          schemas: [envelopeRef(400, unparsable.error, unparsable.message)]
+        }
+      ]);
+    }
+    found.push([
+      413,
+      {
+        description: "Body exceeded the configured size limit",
+        schemas: [
+          envelopeRef(413, "BODY_TOO_LARGE", "Body exceeds the configured limit")
+        ]
+      }
+    ]);
+  }
+  found.push([
+    500,
+    {
+      description: "The request failed and nothing mapped the failure",
+      schemas: [
+        envelopeRef(500, "INTERNAL_SERVER_ERROR", "Internal Server Error")
+      ]
+    }
+  ]);
+  return found;
+}
+function merge(list, envelopes) {
+  const schemas = distinct(list.flatMap((answer) => answer.schemas));
+  const worded = list.filter((answer) => !answer.placeholder);
+  const headers = {};
+  for (const answer of list) {
+    for (const [name, header] of Object.entries(answer.headers ?? {})) {
+      headers[name] ??= header;
     }
-    add(413, {
-      description: "Body exceeded the configured size limit",
-      schema: envelopeRef(413, "BODY_TOO_LARGE", "Body exceeds the configured limit")
-    });
-  }
-  add(500, {
-    description: "The request failed and nothing mapped the failure",
-    schema: envelopeRef(500, "INTERNAL_SERVER_ERROR", "Internal Server Error")
-  });
-  const responses = {};
-  for (const [status, list] of failures) {
-    responses[status] = merge(declared[status], list);
   }
-  return responses;
+  return {
+    description: (worded.length > 0 ? worded : list).map((answer) => answer.description).join("; "),
+    ...Object.keys(headers).length > 0 ? { headers } : {},
+    ...schemas.length > 0 ? {
+      content: {
+        "application/json": { schema: unionOf(schemas, envelopes) }
+      }
+    } : {}
+  };
 }
-function merge(declared, list) {
-  const descriptions = [
-    ...declared ? [declared.description] : [],
-    ...list.map((failure) => failure.description)
-  ];
-  const schemas = distinct([
-    ...declaredSchemas(declared),
-    ...list.map((failure) => failure.schema)
-  ]);
+function unionOf(schemas, envelopes) {
   const [only] = schemas;
+  if (schemas.length === 1 && only) {
+    return only;
+  }
+  const mapping = {};
+  for (const schema of schemas) {
+    const ref = schema.$ref;
+    const code = typeof ref === "string" ? envelopes.codeOf(ref) : undefined;
+    if (typeof ref !== "string" || code === undefined) {
+      return { anyOf: schemas };
+    }
+    mapping[code] = ref;
+  }
   return {
-    description: descriptions.join("; "),
-    ...schemas.length === 1 && only ? { content: { "application/json": { schema: only } } } : { content: { "application/json": { schema: { anyOf: schemas } } } }
+    anyOf: schemas,
+    discriminator: { propertyName: "error", mapping }
   };
 }
-function declaredSchemas(declared) {
-  const schema = declared?.content?.["application/json"]?.schema;
-  return schema ? [schema] : [];
-}
 function distinct(schemas) {
   const seen = new Set;
   return schemas.filter((schema) => {
@@ -364,34 +594,23 @@ function distinct(schemas) {
     return true;
   });
 }
-function jsonResponse(schema, description, warn) {
-  const described = emitted(schema, "a response", warn);
-  if (!described) {
-    return { description };
-  }
-  return {
-    description,
-    content: { "application/json": { schema: described } }
-  };
-}
-function hasSuccess(declared) {
-  return Object.keys(declared).some((status) => status.startsWith("2"));
-}
 function describeStatus(status) {
   if (status === "204") {
     return "No content";
   }
-  return status.startsWith("2") ? "Successful response" : `Response ${status}`;
+  return status.startsWith("2") ? "Successful response" : errorBody(Number(status)).message;
 }
-function envelope(status, error, message) {
+function envelope(status, error, message, fields = {}) {
+  const own = {
+    status: { type: "integer", const: status },
+    message: message ? { type: "string", examples: [message] } : { type: "string" },
+    error: error ? { type: "string", const: error } : { type: "string" }
+  };
+  const added = Object.keys(fields).filter((name) => !Object.hasOwn(own, name));
   return {
     type: "object",
-    required: ["status", "message", "error"],
-    properties: {
-      status: { type: "integer", const: status },
-      message: message ? { type: "string", examples: [message] } : { type: "string" },
-      error: error ? { type: "string", const: error } : { type: "string" }
-    }
+    required: ["status", "message", "error", ...added],
+    properties: { ...fields, ...own }
   };
 }
 function validationFailed(status) {
@@ -433,14 +652,24 @@ import { onMount, route } from "@tetsujs/core";
 // packages/openapi/src/page.ts
 var defaults = {
   scalar: {
-    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
+    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.72.1/dist/browser/standalone.js",
+    integrity: {
+      script: "sha384-U11tb2XnKvmwt8RlTvnwUnYgrN+ur4Xyh9htLhjajWNR/Oyl5AX5DEz00qRmlrmK"
+    }
   },
   "swagger-ui": {
-    script: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
-    style: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css"
+    script: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.0/swagger-ui-bundle.js",
+    style: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.0/swagger-ui.css",
+    integrity: {
+      script: "sha384-YDALVcy8kj8yltLBVi1vBiBAUqdxvus673gM8XKwiy6aDUJFXivF/KCufekjYbVf",
+      style: "sha384-Ov4/wv3j2bmct8cDc5X4ngJZohVPzEmc6uDPH8WeljUxO5vtoykvMEfbu9Vh6RaW"
+    }
   },
   redoc: {
-    script: "https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js"
+    script: "https://cdn.jsdelivr.net/npm/redoc@2.5.4/bundles/redoc.standalone.js",
+    integrity: {
+      script: "sha384-w447zOpYfw/1Tv/5AK9NfHTlQIqE3RVR6KY62jCyy9zNDgO64cMwGGP1Fj0zJVf5"
+    }
   }
 };
 function docsPage(options) {
@@ -454,11 +683,11 @@ function docsPage(options) {
     '<meta charset="utf-8" />',
     '<meta name="viewport" content="width=device-width, initial-scale=1" />',
     `<title>${title}</title>`,
-    assets.style ? `<link rel="stylesheet" href="${escapeHtml(assets.style)}" />` : "",
+    assets.style ? `<link rel="stylesheet" href="${escapeHtml(assets.style)}"${verified(assets.integrity?.style)} />` : "",
     "</head>",
     "<body>",
     body(options.ui, url),
-    `<script src="${escapeHtml(assets.script)}"></script>`,
+    `<script src="${escapeHtml(assets.script)}"${verified(assets.integrity?.script)}></script>`,
     bootstrap(options.ui, url),
     "</body>",
     "</html>"
@@ -485,6 +714,9 @@ function bootstrap(ui, url) {
   ].join(`
 `);
 }
+function verified(integrity) {
+  return integrity ? ` integrity="${escapeHtml(integrity)}" crossorigin="anonymous"` : "";
+}
 function escapeHtml(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 }
@@ -495,7 +727,8 @@ class DocsController {
   json;
   ui;
   document;
-  constructor(options, documentPath, uiPath, page) {
+  page;
+  constructor(options, documentPath, uiPath) {
     this.options = options;
     const hidden = !options.documentSelf;
     const json = route({
@@ -508,12 +741,12 @@ class DocsController {
       method: "GET",
       path: "/docs",
       docs: { summary: "Rendered documentation", tags: ["docs"], hidden },
-      handler: () => new Response(page, {
+      handler: () => new Response(this.page, {
         headers: { "content-type": "text/html; charset=utf-8" }
       })
     });
     this.json = { ...json, path: documentPath };
-    this.ui = { ...ui, path: uiPath };
+    this.ui = options.ui === false ? undefined : { ...ui, path: uiPath };
   }
   [onMount](app) {
     const generated = openapi(app, {
@@ -521,6 +754,17 @@ class DocsController {
       ...this.options.servers ? { servers: this.options.servers } : {}
     });
     this.document = generated.document;
+    const ui = this.options.ui ?? "scalar";
+    const json = 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) {
       report(warning);
@@ -528,15 +772,7 @@ class DocsController {
   }
 }
 function docs(options) {
-  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);
+  return new DocsController(options, options.path ?? "/openapi.json", options.uiPath ?? "/docs");
 }
 function warn(warning) {
   console.warn(`[openapi] ${warning.route}: ${warning.message}`);
@@ -548,15 +784,17 @@ function openapi(app, options) {
   const warnings = [];
   const schemes = {};
   const components = schemaComponents();
+  const envelopes2 = envelopes(components);
   const ids = operationIds();
+  const described = app.entries.filter((entry) => !entry.ws && !entry.def.docs?.hidden);
+  for (const entry of described) {
+    declareEnvelopes(entry, envelopes2);
+  }
   const occupied = new Map;
-  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}`;
-    const operation = operationOf(entry, app.options, components, ids, (message) => {
+    const operation = operationOf(entry, app.options, components, envelopes2, ids, (message) => {
       warnings.push({ route, message });
     });
     for (const requirement of contributionsOf(entry.hooks).security) {
@@ -613,5 +851,5 @@ export {
   secured
 };
 
-//# debugId=7F7340DB513FEEB464756E2164756E21
+//# debugId=8D8E4C09AE6F825C64756E2164756E21
 //# sourceMappingURL=index.js.map