blume 2.0.3 → 2.1.1

package/src/openapi/overlay.ts

@@ -0,0 +1,256 @@
+import { exec, query } from "jsonpath-rfc9535";
+import { z } from "zod";
+
+import type { JsonValue } from "../core/adapter.ts";
+
+/**
+ * OpenAPI Overlays: the OpenAPI Initiative's format for changing an API
+ * description without editing it — an ordered list of actions, each an RFC
+ * 9535 JSONPath `target` with an `update` to merge in, a `copy` of another
+ * node to merge in, or `remove`. A spec generated by another tool or owned by
+ * another team can then carry docs-only changes (better descriptions, hidden
+ * internal operations, a public server URL) in a file of its own.
+ *
+ * Implements Overlay Specification 1.0 and 1.1 over `jsonpath-rfc9535`, which
+ * passes the JSONPath compliance suite in full, as the spec requires. The
+ * documents here are already parsed; `parse.ts` reads the files.
+ */
+
+/** An overlay document or action that doesn't follow the spec. */
+export class OverlayError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OverlayError";
+  }
+}
+
+/** An object node, the only kind that holds named properties. */
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+/** A node that holds other nodes: where a match's parent can be. */
+type JsonContainer = JsonObject | JsonValue[];
+
+const isObject = (value: JsonValue | undefined): value is JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * A parsed YAML or JSON mapping, as the document an overlay acts on: the
+ * parser's own types say nothing of JSON, but what it parses is JSON.
+ */
+export const isJsonObject = <Value>(
+  value: Value
+): value is Value & JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isContainer = (value: JsonValue | undefined): value is JsonContainer =>
+  typeof value === "object" && value !== null;
+
+const isIndex = (key: string | number | undefined): key is number =>
+  typeof key === "number";
+
+/** An object, an array, or anything else: what update merging keys on. */
+type MergeKind = "array" | "object" | "primitive";
+
+const mergeKindOf = (value: JsonValue): MergeKind => {
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  return isObject(value) ? "object" : "primitive";
+};
+
+/** A merge kind in a sentence. */
+const MERGE_KIND_PHRASE: Record<MergeKind, string> = {
+  array: "an array",
+  object: "an object",
+  primitive: "a primitive value",
+};
+
+const actionSchema = z.looseObject({
+  /** A JSONPath expression selecting one node to merge into the targets (1.1). */
+  copy: z.string().optional(),
+  description: z.string().optional(),
+  /** Remove every target from the map or array it's in. */
+  remove: z.boolean().default(false),
+  /** An RFC 9535 JSONPath expression selecting the nodes to act on. */
+  target: z.string().min(1),
+  /** A value merged into every target. */
+  update: z.json().optional(),
+});
+
+/** A validated overlay action. */
+type OverlayAction = z.output<typeof actionSchema>;
+
+const overlaySchema = z.looseObject({
+  actions: z.array(actionSchema).min(1),
+  extends: z.string().optional(),
+  info: z.looseObject({ title: z.string(), version: z.string() }),
+  overlay: z.string().regex(/^1\.[01]\.\d+$/u, {
+    message: "must be an Overlay Specification version, 1.0.x or 1.1.x",
+  }),
+});
+
+/** A validated overlay document. */
+export type OverlayDocument = z.output<typeof overlaySchema>;
+
+/** Validate a parsed overlay document, naming the file in any error. */
+export const overlayDocument = <Value>(
+  value: Value,
+  name: string
+): OverlayDocument => {
+  const parsed = overlaySchema.safeParse(value);
+  if (parsed.success) {
+    return parsed.data;
+  }
+  const [issue] = parsed.error.issues;
+  const at = issue?.path.length ? `\`${issue.path.join(".")}\` ` : "";
+  throw new OverlayError(
+    `${name} is not an overlay document: ${at}${issue?.message ?? "invalid"}.`
+  );
+};
+
+/** A matched node, where it sits, and how to reach it. */
+interface Match {
+  key?: string | number;
+  parent?: JsonContainer;
+  value: JsonValue;
+}
+
+/** The nodes `expression` selects, each with its parent (none for the root). */
+const select = (document: JsonValue, expression: string): Match[] => {
+  const matches: Match[] = [];
+  exec(document, expression, (value, path) => {
+    let parent: JsonValue = document;
+    for (const key of path.slice(0, -1)) {
+      // SAFETY: the path is one the query walked, so every step is a key of
+      // the container before it.
+      parent = (parent as Record<string | number, JsonValue>)[key] ?? null;
+    }
+    const key = path.at(-1);
+    matches.push(
+      key === undefined || !isContainer(parent)
+        ? { value }
+        : { key, parent, value }
+    );
+  });
+  return matches;
+};
+
+/**
+ * Merge `patch` into `target` as the spec says: objects recursively, arrays
+ * by concatenation, a primitive replaced by a primitive. Returns the merged
+ * value; any other pairing throws.
+ */
+const merge = (target: JsonValue, patch: JsonValue, at: string): JsonValue => {
+  if (isObject(target) && isObject(patch)) {
+    for (const [key, value] of Object.entries(patch)) {
+      // Only recurse into the target's own keys, so a `__proto__` or
+      // `constructor` key can't reach a prototype.
+      target[key] = Object.hasOwn(target, key)
+        ? merge(target[key] ?? null, value, `${at}.${key}`)
+        : structuredClone(value);
+    }
+    return target;
+  }
+  if (Array.isArray(target) && Array.isArray(patch)) {
+    target.push(...structuredClone(patch));
+    return target;
+  }
+  if (
+    mergeKindOf(target) === "primitive" &&
+    mergeKindOf(patch) === "primitive"
+  ) {
+    return patch;
+  }
+  throw new OverlayError(
+    `can't merge ${MERGE_KIND_PHRASE[mergeKindOf(patch)]} into ${MERGE_KIND_PHRASE[mergeKindOf(target)]} at ${at}`
+  );
+};
+
+/** Remove each match from its container, later siblings first. */
+const removeAll = (matches: Match[]): void => {
+  for (const { key, parent } of matches.toReversed()) {
+    if (Array.isArray(parent) && isIndex(key)) {
+      parent.splice(key, 1);
+    } else if (isObject(parent) && key !== undefined && !isIndex(key)) {
+      // oxlint-disable-next-line typescript/no-dynamic-delete -- an overlay target's key is only known at run time
+      delete parent[key];
+    } else {
+      throw new OverlayError("can't remove the document itself");
+    }
+  }
+};
+
+/**
+ * Merge `patch` into every match, which must all be objects, all arrays, or
+ * all primitives. A primitive match is replaced in its parent.
+ */
+const mergeAll = (matches: Match[], patch: JsonValue, target: string) => {
+  const kinds = new Set(matches.map((match) => mergeKindOf(match.value)));
+  if (kinds.size > 1) {
+    throw new OverlayError(
+      `its target selects a mix of ${[...kinds].toSorted().join(", ")} values, and an update needs all one kind`
+    );
+  }
+  for (const { key, parent, value } of matches) {
+    const merged = merge(value, patch, target);
+    if (merged !== value && parent !== undefined && key !== undefined) {
+      // SAFETY: `key` came from walking `parent`, so it indexes it.
+      (parent as Record<string | number, JsonValue>)[key] = merged;
+    }
+  }
+};
+
+/** The single node a `copy` expression selects, cloned. */
+const copied = (document: JsonValue, expression: string): JsonValue => {
+  const values = query(document, expression);
+  const [value] = values;
+  if (values.length !== 1 || value === undefined) {
+    throw new OverlayError(
+      `its copy expression "${expression}" selects ${values.length} nodes, and copy needs exactly one`
+    );
+  }
+  return structuredClone(value);
+};
+
+const applyAction = (document: JsonValue, action: OverlayAction): void => {
+  const matches = select(document, action.target);
+  if (matches.length === 0) {
+    return;
+  }
+  if (action.remove) {
+    removeAll(matches);
+    return;
+  }
+  const patch =
+    action.update ??
+    (action.copy === undefined ? undefined : copied(document, action.copy));
+  if (patch !== undefined) {
+    mergeAll(matches, patch, action.target);
+  }
+};
+
+/**
+ * Apply an overlay to a parsed document, in place and in action order: each
+ * action sees the result of the one before. A target that matches nothing
+ * changes nothing. Throws an {@link OverlayError} naming the overlay file and
+ * the action that failed.
+ */
+export const applyOverlay = (
+  document: JsonValue,
+  overlay: OverlayDocument,
+  name: string
+): void => {
+  for (const [index, action] of overlay.actions.entries()) {
+    try {
+      applyAction(document, action);
+    } catch (error) {
+      // SAFETY: the JSONPath parser and this module throw Error instances.
+      const { message } = error as Error;
+      throw new OverlayError(
+        `${name} action ${index + 1} (${action.target}): ${message}`
+      );
+    }
+  }
+};

package/src/openapi/parse.ts

@@ -4,7 +4,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 import type * as ConverterModule from "@asyncapi/converter";
 import { normalize, upgrade } from "@scalar/openapi-parser";
 import pRetry, { AbortError } from "p-retry";
-import { isAbsolute, join } from "pathe";
+import { dirname, isAbsolute, join, resolve } from "pathe";
 import type * as UndiciModule from "undici";
 
 import {
@@ -15,15 +15,21 @@ import { nodeRequire } from "../core/node-require.ts";
 import { hashText } from "../core/sources/cache.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
 import { normalizeAsyncApiDocument } from "./asyncapi.ts";
+import { operationLabel } from "./checks.ts";
+import type { SpecIssue } from "./checks.ts";
 import { buildGraphqlDocument } from "./graphql-build.ts";
 import type { GraphqlDocument } from "./graphql.ts";
+import { HTTP_METHODS } from "./model.ts";
 import type { ApiDocument } from "./model.ts";
+import { applyOverlay, isJsonObject, overlayDocument } from "./overlay.ts";
 import { SpecDependencyError } from "./spec-dependency-error.ts";
 
 /**
  * Spec loading and normalization. Blume reuses Scalar's parser
  * (`@scalar/openapi-parser`) to read a spec (YAML or JSON), then upgrade Swagger
  * 2.0 / OpenAPI 3.0 documents to 3.1 so the renderer only handles one shape.
+ * OpenAPI 3.2 is backward compatible with 3.1, so a 3.2 document is read as
+ * written.
  * Internal `$ref`s are deliberately left in place (see `model.ts`).
  *
  * Remote (`http(s)`) specs are fetched defensively — bounded per attempt, retried
@@ -57,6 +63,8 @@ const PROXY_ENV_VARS = [
 
 export interface ParsedSpec {
   document: ApiDocument;
+  /** `x-codeSamples` entries whose `$ref` couldn't be inlined. */
+  issues: SpecIssue[];
   warnings: string[];
 }
 
@@ -75,6 +83,11 @@ export class InvalidSpecError extends Error {
 
 /** Where and whether to cache a remote spec's text between runs. */
 export interface SpecFetchOptions {
+  /**
+   * Overlay documents (local paths or `http(s)` URLs) applied in order to
+   * the parsed spec, before it's upgraded. See `overlay.ts`.
+   */
+  overlays?: readonly string[];
   /** Dir for a last-good on-disk copy of a remote spec (offline fallback). */
   cacheDir?: string;
   /**
@@ -310,13 +323,177 @@ const readSpecText = async (
 const isApiDocument = <Value>(value: Value): value is Value & ApiDocument =>
   typeof value === "object" && value !== null;
 
+/**
+ * Read a spec and apply its overlays, in order, to the parsed document as
+ * written (before any upgrade: an overlay targets its spec's own version).
+ * The overlays are read like the spec, local or remote, cached alike.
+ */
+const readOverlaid = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<{ document: ReturnType<typeof normalize>; warnings: string[] }> => {
+  const [read, ...overlays] = await Promise.all(
+    [spec, ...(options.overlays ?? [])].map((path) =>
+      readSpecText(path, root, options)
+    )
+  );
+  const document = normalize(read?.text ?? "");
+  for (const [index, overlay] of overlays.entries()) {
+    const name = options.overlays?.[index] ?? "";
+    const parsed = overlayDocument(normalize(overlay.text), name);
+    // A spec that isn't a mapping has nothing to overlay; the caller
+    // rejects it as it would without overlays.
+    if (isJsonObject(document)) {
+      applyOverlay(document, parsed, name);
+    }
+  }
+  return {
+    document,
+    warnings: [read, ...overlays].flatMap((entry) => entry?.warnings ?? []),
+  };
+};
+
+/**
+ * A spec with its overlays applied, as JSON text: what the Scalar embed
+ * inlines, since it can't apply overlays itself.
+ */
+export const readOverlaidSpec = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<{ text: string; warnings: string[] }> => {
+  const { document, warnings } = await readOverlaid(spec, root, options);
+  return { text: JSON.stringify(document), warnings };
+};
+
+/** A `$ref` in place of an `x-codeSamples` entry's `source`. */
+interface SampleRef {
+  $ref: string;
+}
+
+/** An `x-codeSamples` entry whose `source` is a `$ref` rather than the code. */
+const isRefSample = (value: unknown): value is { source: SampleRef } =>
+  isJsonObject(value) &&
+  isJsonObject(value.source) &&
+  typeof value.source.$ref === "string";
+
+/**
+ * Where a code sample's `$ref` points, in the form `readSpecText` reads: a
+ * URL, or a path resolved against the spec's own location. `undefined` for
+ * a JSON pointer (`#/…`, or a file with a fragment), which names a spot
+ * inside a document rather than a file of code.
+ */
+const sampleTarget = (
+  ref: string,
+  spec: string,
+  root: string
+): string | undefined => {
+  if (ref.includes("#")) {
+    return undefined;
+  }
+  if (URL_SPEC.test(ref)) {
+    return ref;
+  }
+  if (URL_SPEC.test(spec)) {
+    return new URL(ref, spec).href;
+  }
+  return resolve(dirname(isAbsolute(spec) ? spec : join(root, spec)), ref);
+};
+
+/**
+ * Inline each `x-codeSamples` entry whose `source` is a `$ref` to a file of
+ * its own, as Redocly's docs describe (`source: { $ref: ../code_samples/… }`):
+ * `redocly bundle` inlines those, and a spec read as written doesn't. Each
+ * file is read relative to the spec,
+ * the way the spec itself was (local, or fetched and cached), so the sample
+ * renders like a written-out one. An entry that can't be read is left out of
+ * the page, with a warning, rather than dropped without a sign.
+ */
+const inlineSampleRefs = async (
+  document: ApiDocument,
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<SpecIssue[]> => {
+  const reads: Promise<SpecIssue | undefined>[] = [];
+  const inline = async (
+    entry: { source: SampleRef | string },
+    ref: string,
+    label: string
+  ): Promise<SpecIssue | undefined> => {
+    const target = sampleTarget(ref, spec, root);
+    if (target === undefined) {
+      return {
+        code: "BLUME_OPENAPI_CODE_SAMPLE_REF",
+        message: `${label} has an \`x-codeSamples\` entry whose \`source\` is a $ref to "${ref}", a spot inside a document, which Blume doesn't resolve, so the sample is left out.`,
+        suggestion:
+          "Point the `$ref` at a file that holds only the sample's code, or write the code out in `source`.",
+      };
+    }
+    try {
+      const { text } = await readSpecText(target, root, options);
+      entry.source = text;
+      return undefined;
+    } catch (error) {
+      // SAFETY: a failed read throws a Node error, and a failed fetch an
+      // Error (`attemptFetch` wraps anything else); only the message is shown.
+      const { message } = error as Error;
+      return {
+        code: "BLUME_OPENAPI_CODE_SAMPLE_REF",
+        message: `${label} has an \`x-codeSamples\` entry whose \`source\` is a $ref to "${ref}", which couldn't be read (${message}), so the sample is left out.`,
+        suggestion:
+          "Check the path, which is relative to the spec, or write the code out in `source`.",
+      };
+    }
+  };
+  const visit = (
+    name: string,
+    item: NonNullable<ApiDocument["paths"]>[string] | undefined,
+    webhook: boolean
+  ): void => {
+    if (!isJsonObject(item) || "$ref" in item) {
+      return;
+    }
+    for (const method of HTTP_METHODS) {
+      const operation = item[method];
+      // The spelling `customCodeSamples` renders: the current one wins.
+      const samples = isJsonObject(operation)
+        ? (operation["x-codeSamples"] ?? operation["x-code-samples"])
+        : undefined;
+      for (const entry of Array.isArray(samples) ? samples : []) {
+        if (isRefSample(entry)) {
+          reads.push(
+            inline(
+              entry,
+              entry.source.$ref,
+              operationLabel(name, method, webhook)
+            )
+          );
+        }
+      }
+    }
+  };
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
+    visit(path, item, false);
+  }
+  for (const [name, item] of Object.entries(document.webhooks ?? {})) {
+    visit(name, item, true);
+  }
+  const issues = await Promise.all(reads);
+  return issues.filter((issue) => issue !== undefined);
+};
+
 export const parseSpec = async (
   spec: string,
   root: string,
   options: SpecFetchOptions = {}
 ): Promise<ParsedSpec> => {
-  const { text, warnings } = await readSpecText(spec, root, options);
-  const normalized = normalize(text);
+  const { document: normalized, warnings } = await readOverlaid(
+    spec,
+    root,
+    options
+  );
   const { specification } = upgrade(normalized);
   // Reject a non-mapping here so the renderer never sees a non-document.
   if (!isApiDocument(specification)) {
@@ -324,7 +501,8 @@ export const parseSpec = async (
       `${spec} is not a valid OpenAPI document (expected a YAML or JSON object).`
     );
   }
-  return { document: specification, warnings };
+  const issues = await inlineSampleRefs(specification, spec, root, options);
+  return { document: specification, issues, warnings };
 };
 
 export interface ParsedAsyncApiSpec {

package/src/openapi/references.ts

@@ -1,6 +1,9 @@
+import { isAbsolute, join } from "pathe";
+
 import { normalizeRoute, withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { trimChar } from "../core/trim.ts";
+import type { GraphqlAuthOptions } from "../reference/options.ts";
 import type { ScalarOptions } from "../reference/scalar.ts";
 import type { ResolvedReferenceAdapter } from "../reference/schema.ts";
 
@@ -28,8 +31,8 @@ export type BlumeReferenceKind = Exclude<ReferenceKind, "scalar">;
 
 /** Per-adapter display options for the Blume renderer. */
 export interface ReferenceDisplay {
-  /** Code-sample languages shown per operation. */
-  codeSamples: string[];
+  /** Code-sample languages shown per operation; `false` for none. */
+  codeSamples: string[] | false;
   /** Whether nested schema rows start expanded. */
   expandSchemas: boolean;
   /**
@@ -54,6 +57,12 @@ export interface ReferenceSource {
    */
   basePath: string;
   label: string;
+  /**
+   * The source's own `label`, when it sets one: it names the sidebar group
+   * of the source's route. An unlabeled source's group keeps the name its
+   * route gives it.
+   */
+  groupLabel?: string;
   /** Whether generated pages are included in llms.txt/llms-full.txt. */
   includeInLlms: boolean;
   /** Whether generated pages are included in site search. */
@@ -67,11 +76,18 @@ export interface ReferenceSource {
   seoDescriptionSuffix: boolean;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
+  /**
+   * OpenAPI Overlay documents applied to `spec` in order (`openapi()` and
+   * `scalar()` only).
+   */
+  overlays?: string[];
   /**
    * URL of the live GraphQL endpoint the playground and code samples target
    * (GraphQL only — a schema, unlike an OpenAPI document, names no server).
    */
   endpoint?: string;
+  /** How the GraphQL endpoint authenticates (GraphQL only). */
+  auth?: GraphqlAuthOptions;
   /**
    * The `scalar()` adapter's own options (`scalar` kind only): `theme` plus
    * any Scalar config forwarded verbatim to `<ScalarComponent>`, which takes
@@ -176,6 +192,7 @@ const scalarOptionsOf = (
 
 /** A source row with every kind's fields reconciled onto one shape. */
 interface SourceRow {
+  auth?: GraphqlAuthOptions;
   endpoint?: string;
   includeInLlms: boolean;
   includeInSearch: boolean;
@@ -184,13 +201,14 @@ interface SourceRow {
   route?: string;
   seoDescriptionSuffix: boolean;
   spec: string;
+  overlays?: string[];
 }
 
 /**
  * One row per source, with the kind-specific fields already reconciled: a
- * GraphQL source's `endpoint` falls back to the adapter-wide default (the
- * common single-schema case pairs it with the `spec` shorthand); the other
- * kinds have no endpoint at all. A Scalar source carries only `noindex` of
+ * GraphQL source's `endpoint` and `auth` fall back to the adapter-wide
+ * defaults (the common single-schema case pairs them with the `spec`
+ * shorthand); the other kinds have neither. A Scalar source carries only `noindex` of
  * the per-source controls — the embed sits outside search and llms.txt, so
  * the other two read as off.
  */
@@ -198,6 +216,7 @@ const sourceRowsOf = (adapter: ResolvedReferenceAdapter): SourceRow[] => {
   if (adapter.kind === "graphql") {
     return adapter.options.sources.map((source) => ({
       ...source,
+      auth: source.auth ?? adapter.options.auth,
       endpoint: source.endpoint ?? adapter.options.endpoint,
     }));
   }
@@ -252,9 +271,18 @@ const referencesFor = (
     if (adapter.kind === "scalar") {
       reference.scalar = scalarOptionsOf(adapter.options);
     }
+    if (source.label !== undefined) {
+      reference.groupLabel = source.label;
+    }
     if (source.endpoint !== undefined) {
       reference.endpoint = source.endpoint;
     }
+    if (source.auth !== undefined) {
+      reference.auth = source.auth;
+    }
+    if (source.overlays !== undefined) {
+      reference.overlays = source.overlays;
+    }
     return reference;
   });
 };
@@ -339,6 +367,27 @@ export const blumeReferences = (
   return result;
 };
 
+/** A spec or overlay the parser fetches rather than reads from disk. */
+const REMOTE_SPEC = /^https?:\/\//u;
+
+/**
+ * The local files every reference reads, as absolute paths: each spec and
+ * overlay that isn't an `http(s)` URL, resolved from the project root the way
+ * the parser resolves them. `blume dev` watches these, so an edit to a spec
+ * regenerates its reference like an edit to a page does.
+ */
+export const referenceSpecFiles = (
+  config: ResolvedConfig,
+  root: string
+): string[] => [
+  ...new Set(
+    resolveReferences(config)
+      .flatMap((ref) => [ref.spec, ...(ref.overlays ?? [])])
+      .filter((path) => !REMOTE_SPEC.test(path))
+      .map((path) => (isAbsolute(path) ? path : join(root, path)))
+  ),
+];
+
 /** Whether any reference is Scalar-rendered (gates the Scalar pages). */
 export const hasScalarReferences = (config: ResolvedConfig): boolean =>
   resolveReferences(config).some((ref) => ref.kind === "scalar");
@@ -363,11 +412,18 @@ export const builtinProxyReferences = (
       ref.display.playground.proxy === true
   );
 
+/**
+ * Whether hand-written endpoint pages (`api` frontmatter) send their Try it
+ * requests through the built-in proxy: `api.playground.proxy: true`.
+ */
+export const apiPagesUseBuiltinProxy = (config: ResolvedConfig): boolean =>
+  config.api.playground.enabled && config.api.playground.proxy === true;
+
 /**
  * Whether the built-in playground CORS proxy endpoint (`/_api-proxy`) must be
  * generated: some Blume-rendered reference's playground opted into it with
- * `proxy: true`. Shared by the server feature gate and the generator so the
- * two can never disagree.
+ * `proxy: true`, or the hand-written endpoint pages' did. Shared by the server
+ * feature gate and the generator so the two can never disagree.
  */
 export const needsPlaygroundProxy = (config: ResolvedConfig): boolean =>
-  builtinProxyReferences(config).length > 0;
+  builtinProxyReferences(config).length > 0 || apiPagesUseBuiltinProxy(config);

package/src/openapi/render-mdx.ts

@@ -270,7 +270,8 @@ const operationDescription = (
     // method (see `extractGraphqlOperations`).
     subject = `${operation.path} ${GRAPHQL_MEMBER_PHRASES[operation.method as GraphqlMember]}`;
   } else {
-    subject = `${operation.method.toUpperCase()} ${operation.path} endpoint`;
+    // A webhook is a request the API sends, named rather than pathed.
+    subject = `${operation.method.toUpperCase()} ${operation.path} ${operation.webhook ? "webhook" : "endpoint"}`;
   }
   const suffix = `Reference for the ${subject} in the ${apiPhrase(spec)}.`;
   // Room for the joining space and the period `asSentence` may add, so a
@@ -348,6 +349,9 @@ export const operationMdx = (
     sidebar.badge = method;
   }
   const tags = graphql ? [operation.tag] : [operation.tag, method];
+  if (operation.webhook) {
+    tags.push("Webhook");
+  }
   return {
     body: withDescription(
       description,