@tetsujs/openapi 0.1.0

package/src/page.ts

@@ -0,0 +1,139 @@
+/**
+ * The HTML page that renders a document.
+ *
+ * Returns a string and mounts nothing: which path serves the page, and
+ * whether one is served at all, is the application's decision like every
+ * other route.
+ *
+ * The renderers themselves are loaded from a CDN. Vendoring Scalar or
+ * Swagger UI would put megabytes of somebody else's bundle into a
+ * dependency-free repository, so the trade is stated instead of hidden:
+ * the documentation page — and only it — needs the network, and the URL is
+ * a parameter, so a self-hosted copy is one option away. Nothing is
+ * fetched unless this function is called.
+ *
+ * @module
+ */
+
+/** The renderers this package knows how to bootstrap. */
+export type DocsUi = "scalar" | "swagger-ui" | "redoc";
+
+/** Where a renderer is loaded from. */
+export interface DocsAssets {
+  readonly script: string;
+  readonly style?: string;
+}
+
+/** What the page needs to know. */
+export interface DocsPageOptions {
+  /** Which renderer to bootstrap. */
+  readonly ui: DocsUi;
+
+  /** Where the document is served — the page fetches it from there. */
+  readonly documentUrl: string;
+
+  /** Browser title; defaults to `"API documentation"`. */
+  readonly title?: string;
+
+  /** Overrides the CDN URLs, for a pinned version or a self-hosted copy. */
+  readonly assets?: DocsAssets;
+}
+
+const defaults: Record<DocsUi, DocsAssets> = {
+  scalar: {
+    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference",
+  },
+  "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",
+  },
+  redoc: {
+    script: "https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js",
+  },
+};
+
+/**
+ * Builds the documentation page.
+ *
+ * Called by `docs()` for the page it serves; call it directly to serve one
+ * from somewhere else.
+ *
+ * @example
+ * ```ts
+ * const page = docsPage({ ui: "scalar", documentUrl: "/openapi.json" });
+ *
+ * const ui = route({
+ *   method: "GET",
+ *   path: "/docs",
+ *   handler: () =>
+ *     new Response(page, { headers: { "content-type": "text/html" } }),
+ * });
+ * ```
+ */
+export function docsPage(options: DocsPageOptions): string {
+  const assets = options.assets ?? defaults[options.ui];
+  const title = escapeHtml(options.title ?? "API documentation");
+  const url = escapeHtml(options.documentUrl);
+
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<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)}" />`
+      : "",
+    "</head>",
+    "<body>",
+    body(options.ui, url),
+    `<script src="${escapeHtml(assets.script)}"></script>`,
+    bootstrap(options.ui, url),
+    "</body>",
+    "</html>",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function body(ui: DocsUi, url: string): string {
+  if (ui === "scalar") {
+    return `<script id="api-reference" data-url="${url}"></script>`;
+  }
+
+  if (ui === "redoc") {
+    return `<redoc spec-url="${url}"></redoc>`;
+  }
+
+  return '<div id="swagger-ui"></div>';
+}
+
+function bootstrap(ui: DocsUi, url: string): string {
+  if (ui !== "swagger-ui") {
+    return "";
+  }
+
+  return [
+    "<script>",
+    `SwaggerUIBundle({ url: "${url}", dom_id: "#swagger-ui" });`,
+    "</script>",
+  ].join("\n");
+}
+
+/**
+ * Escapes the values that reach the markup.
+ *
+ * The document URL and the title come from the application, but they are
+ * still values interpolated into HTML — a quote in either would break out
+ * of the attribute it sits in.
+ */
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}

package/src/parameters.ts

@@ -0,0 +1,145 @@
+/**
+ * Path templates and request parameters.
+ *
+ * The framework's path syntax is Bun's — `:param` and a trailing `*` —
+ * while OpenAPI templates variables as `{param}`. The conversion happens
+ * here, together with the parameter objects the template then requires:
+ * OpenAPI demands that every variable in a path be declared.
+ *
+ * @module
+ */
+
+import type { AnySchema } from "@tetsujs/core";
+import type { ParameterObject } from "./document.ts";
+import { emitted } from "./emit.ts";
+
+/** The name a wildcard segment is documented under. */
+export const wildcardName = "wildcard";
+
+/**
+ * Rewrites a route path as an OpenAPI path template.
+ *
+ * A wildcard becomes an ordinary variable: OpenAPI has no syntax for
+ * "everything below here", so the closest honest template is a named
+ * segment, documented as such.
+ */
+export function toTemplate(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => {
+      if (segment.startsWith(":")) {
+        return `{${segment.slice(1)}}`;
+      }
+
+      return segment === "*" ? `{${wildcardName}}` : segment;
+    })
+    .join("/");
+}
+
+/** The variables a path template declares, in order. */
+export function templateNames(path: string): string[] {
+  const names: string[] = [];
+
+  for (const segment of path.split("/")) {
+    if (segment.startsWith(":")) {
+      names.push(segment.slice(1));
+    } else if (segment === "*") {
+      names.push(wildcardName);
+    }
+  }
+
+  return names;
+}
+
+/**
+ * Describes the path parameters of a route.
+ *
+ * A `params` schema describes the whole object, so each variable takes the
+ * property of the same name; without one — or without a property for a
+ * given variable — the value is what the router captured: a string.
+ */
+export function pathParameters(
+  path: string,
+  schema: AnySchema | undefined,
+  warn: (message: string) => void,
+): ParameterObject[] {
+  const properties = objectProperties(schema, "params", warn);
+
+  return templateNames(path).map((name) => ({
+    name,
+    in: "path" as const,
+    required: true,
+    ...(name === wildcardName
+      ? {
+          description:
+            "Matches the rest of the path, including further segments.",
+        }
+      : {}),
+    schema: properties[name] ?? { type: "string" },
+  }));
+}
+
+/**
+ * Describes the query, header or cookie parameters of a route.
+ *
+ * All three are objects at the schema level and lists of parameters in a
+ * document, so each declared property becomes one parameter, required when
+ * the schema says so.
+ *
+ * A session cookie is the exception the specification makes itself: a
+ * credential belongs in `securitySchemes` as `apiKey in: cookie`, not
+ * among the parameters. Nothing here can tell one cookie from the other —
+ * that is what an annotation on the hook reading it is for, the same way
+ * `secured()` marks an authenticating hook.
+ */
+export function partParameters(
+  schema: AnySchema | undefined,
+  where: "query" | "header" | "cookie",
+  warn: (message: string) => void,
+): ParameterObject[] {
+  if (!schema) {
+    return [];
+  }
+
+  const described = emitted(schema, `the ${where}`, warn, "input");
+
+  if (!described) {
+    return [];
+  }
+
+  const properties = (described.properties ?? {}) as Record<
+    string,
+    Record<string, unknown>
+  >;
+  const required = new Set(
+    Array.isArray(described.required) ? (described.required as string[]) : [],
+  );
+
+  return Object.entries(properties).map(([name, property]) => ({
+    name,
+    in: where,
+    required: required.has(name),
+    schema: property,
+  }));
+}
+
+function objectProperties(
+  schema: AnySchema | undefined,
+  where: string,
+  warn: (message: string) => void,
+): Record<string, Record<string, unknown>> {
+  if (!schema) {
+    return {};
+  }
+
+  const described = emitted(schema, `the ${where}`, warn, "input");
+
+  if (!described) {
+    return {};
+  }
+
+  return (described.properties ?? {}) as Record<
+    string,
+    Record<string, unknown>
+  >;
+}