@tetsujs/openapi 0.5.3 → 0.6.1

package/dist/src/index.js

@@ -373,8 +373,8 @@ function operationOf(entry, options, components, envelopes, ids, warn) {
   };
 }
 function declareEnvelopes(entry, envelopes) {
-  for (const [status, schema] of declaredResponses(entry)) {
-    const described = schema === null ? undefined : emitted(schema, "", () => {});
+  for (const [status, { body }] of declaredResponses(entry)) {
+    const described = body === null ? undefined : emitted(body, "", () => {});
     const code = envelopes.format.code;
     for (const branch of described ? branchesOf(described, code) : []) {
       const found = code(branch);
@@ -390,9 +390,62 @@ function declaredResponses(entry) {
     return [];
   }
   if ("~standard" in response) {
-    return [["200", response]];
+    return [["200", { body: response }]];
   }
-  return Object.entries(response);
+  return Object.entries(response).map(([status, value]) => [
+    status,
+    asDeclared(value)
+  ]);
+}
+function asDeclared(value) {
+  if (value === null || "~standard" in value) {
+    return { body: value };
+  }
+  return {
+    body: value.body ?? null,
+    ...value.headers === undefined ? {} : { headers: value.headers },
+    ...value.cookies === undefined ? {} : { cookies: value.cookies }
+  };
+}
+function declaredHeaders(declared, warn) {
+  const headers = {};
+  const [properties, required] = shapeOf2(declared.headers, "a response's headers", warn);
+  for (const [name, property] of Object.entries(properties)) {
+    const { description, ...schema } = property;
+    headers[name] = {
+      ...typeof description === "string" ? { description } : {},
+      ...required.has(name) ? { required: true } : {},
+      schema
+    };
+  }
+  const cookies = setCookie(declared.cookies, warn);
+  if (cookies) {
+    headers["set-cookie"] = cookies;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+function setCookie(schema, warn) {
+  const [properties, required] = shapeOf2(schema, "a response's cookies", warn);
+  const names = Object.keys(properties);
+  if (names.length === 0) {
+    return;
+  }
+  const lines = names.map((name) => {
+    const description = properties[name]?.["description"];
+    return typeof description === "string" ? `- \`${name}\`: ${description}` : `- \`${name}\``;
+  });
+  return {
+    description: ["Sets these cookies:", "", ...lines].join(`
+`),
+    ...required.size > 0 ? { required: true } : {},
+    schema: { type: "string" }
+  };
+}
+function shapeOf2(schema, subject, warn) {
+  const described = schema ? emitted(schema, subject, warn, "input") : undefined;
+  const properties = described?.properties ?? {};
+  const required = new Set(Array.isArray(described?.required) ? described.required : []);
+  return [properties, required];
 }
 function branchesFor(schema, status, envelopes, warn) {
   return branchesOf(schema, envelopes.format.code).map((branch) => {
@@ -463,7 +516,7 @@ function derivedId(entry) {
 }
 function requestBody(entry, warn) {
   const declared = entry.def.schema?.body;
-  const bodyType = entry.def.bodyType ?? (declared ? "json" : undefined);
+  const bodyType = entry.def.bodyType ?? (declared || entry.def.rawBody ? "json" : undefined);
   if (!bodyType) {
     return;
   }
@@ -508,15 +561,18 @@ function responses(entry, options, contributed, components, envelopes, warn) {
   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);
+  const declared = declaredResponses(entry);
+  for (const [status, { body, ...rest }] of declared) {
+    const described = body === null ? undefined : emitted(body, "a response", warn);
+    const headers = declaredHeaders({ body, ...rest }, warn);
     add(status, {
       placeholder: describeStatus(status),
       said: described ? wordsOf(described, envelopes) : [],
-      schemas: described ? branchesFor(unionOnly(described), Number(status), envelopes, warn) : []
+      schemas: described ? branchesFor(unionOnly(described), Number(status), envelopes, warn) : [],
+      ...headers === undefined ? {} : { headers }
     });
   }
-  if (![...answers.keys()].some((status) => status.startsWith("2"))) {
+  if (declared.length === 0) {
     add("200", { placeholder: "Successful response", said: [], schemas: [] });
   }
   for (const [status, answer] of failures(entry, options, contributed, components, envelopes, warn)) {
@@ -541,7 +597,7 @@ function failures(entry, options, contributed, components, envelopes, warn) {
     const ref = error === undefined ? components.ref(failureName(status), described) : envelopes.ref(status, error, described, warn);
     return ref;
   };
-  if (schema?.params || schema?.query || schema?.headers || schema?.body) {
+  if (schema?.params || schema?.query || schema?.headers || schema?.cookies || schema?.body) {
     found.push([
       options.validationStatus,
       {
@@ -587,7 +643,7 @@ function failures(entry, options, contributed, components, envelopes, warn) {
       }
     ]);
   }
-  if (schema?.body || entry.def.bodyType) {
+  if (schema?.body || entry.def.bodyType || entry.def.rawBody) {
     const unparsable = parseFailure(entry.def.bodyType);
     if (unparsable) {
       found.push([
@@ -745,6 +801,63 @@ function capitalize(value) {
 function lowerFirst(value) {
   return value.charAt(0).toLowerCase() + value.slice(1);
 }
+
+// packages/openapi/src/refs.ts
+var data = new Set(["const", "default", "enum", "example", "examples"]);
+function unresolvedRefs(node, document) {
+  const unresolved = new Set;
+  const visited = new Map;
+  const pending = [[node, document]];
+  for (let next = pending.pop();next; next = pending.pop()) {
+    const [value, base] = next;
+    if (typeof value !== "object" || value === null) {
+      continue;
+    }
+    const bases = visited.get(value) ?? new Set;
+    if (bases.has(base)) {
+      continue;
+    }
+    visited.set(value, bases.add(base));
+    const schema = value;
+    const resource = !Array.isArray(value) && typeof schema["$id"] === "string" ? schema : base;
+    const ref = Array.isArray(value) ? undefined : schema["$ref"];
+    if (typeof ref === "string" && ref.startsWith("#") && !resolves(ref.slice(1), resource, document)) {
+      unresolved.add(ref);
+    }
+    const children = Object.entries(schema).filter(([keyword]) => Array.isArray(value) || !data.has(keyword));
+    for (let index = children.length - 1;index >= 0; index -= 1) {
+      pending.push([children[index]?.[1], resource]);
+    }
+  }
+  return [...unresolved];
+}
+function resolves(fragment, base, document) {
+  if (fragment === "") {
+    return base !== document;
+  }
+  if (!fragment.startsWith("/")) {
+    return true;
+  }
+  let target = base;
+  for (const token of fragment.slice(1).split("/")) {
+    if (typeof target !== "object" || target === null) {
+      return false;
+    }
+    const key = decoded(token);
+    if (key === undefined || !Object.hasOwn(target, key)) {
+      return false;
+    }
+    target = target[key];
+  }
+  return typeof target === "object" && target !== null || typeof target === "boolean";
+}
+function decoded(token) {
+  try {
+    return decodeURIComponent(token).replaceAll("~1", "/").replaceAll("~0", "~");
+  } catch {
+    return;
+  }
+}
 // packages/openapi/src/controller.ts
 import { onMount, route } from "@tetsujs/core";
 
@@ -787,7 +900,7 @@ function docsPage(options) {
     "<body>",
     body(options.ui, url),
     `<script src="${escapeHtml(assets.script)}"${verified(assets.integrity?.script)}></script>`,
-    bootstrap(options.ui, url),
+    bootstrap(options.ui),
     "</body>",
     "</html>"
   ].filter(Boolean).join(`
@@ -800,15 +913,16 @@ function body(ui, url) {
   if (ui === "redoc") {
     return `<redoc spec-url="${url}"></redoc>`;
   }
-  return '<div id="swagger-ui"></div>';
+  return `<div id="swagger-ui" data-url="${url}"></div>`;
 }
-function bootstrap(ui, url) {
+function bootstrap(ui) {
   if (ui !== "swagger-ui") {
     return "";
   }
   return [
     "<script>",
-    `SwaggerUIBundle({ url: "${url}", dom_id: "#swagger-ui" });`,
+    'const root = document.getElementById("swagger-ui");',
+    'SwaggerUIBundle({ url: root.dataset.url, dom_id: "#swagger-ui" });',
     "</script>"
   ].join(`
 `);
@@ -938,17 +1052,36 @@ function openapi(app, options) {
     };
   }
   const tags = options.tags ? tagsOf(options.tags, used, warnings) : undefined;
-  return {
-    document: {
-      openapi: "3.1.0",
-      info: options.info,
-      ...options.servers ? { servers: options.servers } : {},
-      ...tags ? { tags } : {},
-      paths,
-      ...componentsOf(schemes, components.schemas)
-    },
-    warnings
+  const document = {
+    openapi: "3.1.0",
+    info: options.info,
+    ...options.servers ? { servers: options.servers } : {},
+    ...tags ? { tags } : {},
+    paths,
+    ...componentsOf(schemes, components.schemas)
   };
+  refsOf(document, occupied, warnings);
+  return { document, warnings };
+}
+function refsOf(document, routes, warnings) {
+  const unresolved = (ref) => `refers to "${ref}", which is no schema in the document: references are embedded as they are, and resolve against the document's root`;
+  for (const [template, item] of Object.entries(document.paths)) {
+    for (const [method, operation] of Object.entries(item)) {
+      const route = routes.get(`${method} ${template}`) ?? "";
+      for (const ref of unresolvedRefs(operation, document)) {
+        warnings.push({ route, message: `a schema ${unresolved(ref)}` });
+      }
+    }
+  }
+  const schemas = document.components?.schemas ?? {};
+  for (const [name, schema] of Object.entries(schemas)) {
+    for (const ref of unresolvedRefs(schema, document)) {
+      warnings.push({
+        route: "",
+        message: `components/schemas/${name} ${unresolved(ref)}`
+      });
+    }
+  }
 }
 function tagsOf(described, used, warnings) {
   const tags = Object.entries(described).map(([name, description]) => ({ name, description }));
@@ -988,5 +1121,5 @@ export {
   secured
 };
 
-//# debugId=3A3B60517CA111D464756E2164756E21
+//# debugId=A9BC9A29B6C6C1DA64756E2164756E21
 //# sourceMappingURL=index.js.map