blume 2.1.3 → 2.2.0

package/src/components/openapi/Operation.astro

@@ -159,6 +159,7 @@ const model =
         parameters: params,
         path: ref.path,
         requestBody,
+        responses,
         schemas,
         security,
         // An operation's own `servers` override its path item's, which
@@ -268,6 +269,7 @@ const callbackParts = (entry: CallbackEntry) => ({
           <ParametersTable parameters={params} schemas={schemas} />
           {requestBody && (
             <RequestBody
+              components={components}
               direction={bodyDirection}
               expandAll={spec.expandSchemas}
               requestBody={requestBody}
@@ -321,9 +323,11 @@ const callbackParts = (entry: CallbackEntry) => ({
                       />
                       {parts.requestBody && (
                         <RequestBody
+                          components={components}
                           direction="response"
                           expandAll={spec.expandSchemas}
                           level={4}
+                          name={`callback-${entry.key}`}
                           requestBody={parts.requestBody}
                           schemas={schemas}
                         />

package/src/components/openapi/PanelTabs.astro

@@ -28,16 +28,22 @@ interface Props {
   copy?: boolean;
   /** Render tab labels in a monospace face (status codes). */
   mono?: boolean;
+  /**
+   * Names this tab set in its element ids, for a heading that repeats on
+   * the page (a callback's request body examples). Defaults to the heading.
+   */
+  name?: string;
 }
 
-const { heading, panels, copy = false, mono = false } = Astro.props;
+const { heading, panels, copy = false, mono = false, name = heading } =
+  Astro.props;
 
 // A stable per-instance id prefix so tab/tabpanel pairs can reference each
 // other without colliding across the multiple PanelTabs on one page (the
-// heading is unique per rail group; panel keys are unique within a group).
+// name is unique per tab set; panel keys are unique within a set).
 const NON_ID = /[^a-z0-9]+/gu;
 const idFor = (kind: "tab" | "panel", key: string): string =>
-  ["panel-tabs", heading, kind, key]
+  ["panel-tabs", name, kind, key]
     .map((part) => part.toLowerCase().replace(NON_ID, "-"))
     .join("-");
 

package/src/components/openapi/RequestBody.astro

@@ -1,22 +1,31 @@
 ---
+import data from "blume:data";
+
+import { highlightCode } from "../../markdown/index.ts";
 import Description from "./Description.astro";
-import type { SchemaLike } from "./helpers.ts";
+import { preferredMedia } from "./example-panels.ts";
+import {
+  type ComponentsLike,
+  type MediaLike,
+  namedExamples,
+  type SchemaLike,
+  toJson,
+} from "./helpers.ts";
+import PanelTabs from "./PanelTabs.astro";
 import type { SchemaDirection } from "./schema-tree.ts";
 import SchemaTable from "./SchemaTable.astro";
 
-interface MediaTypeLike {
-  schema?: SchemaLike;
-}
-
 interface RequestBodyLike {
   description?: string;
   required?: boolean;
-  content?: Record<string, MediaTypeLike>;
+  content?: Record<string, MediaLike>;
 }
 
 interface Props {
   requestBody: RequestBodyLike;
   schemas: Record<string, SchemaLike>;
+  /** The document's `components`, which `$ref`'d examples resolve against. */
+  components?: ComponentsLike;
   expandAll?: boolean;
   /** The heading's level: 2 on an operation, deeper inside a callback. */
   level?: number;
@@ -25,20 +34,38 @@ interface Props {
    * callback, which the API sends, reads like a response instead.
    */
   direction?: SchemaDirection;
+  /** Names the body's example tabs in their element ids (one per callback). */
+  name?: string;
 }
 
 const {
   requestBody,
   schemas,
+  components,
   expandAll = false,
   level = 2,
   direction = "request",
+  name = "request-body",
 } = Astro.props;
 
-const entries = Object.entries(requestBody.content ?? {});
-const chosen = entries.find(([type]) => type.includes("json")) ?? entries[0];
+const chosen = preferredMedia(requestBody.content);
 const contentType = chosen?.[0] ?? "application/json";
 const schema = chosen?.[1]?.schema ?? {};
+
+// A body whose `examples` map names two or more shows each, under its name:
+// the code samples and Try it start from the first one only.
+const examplePanels = await Promise.all(
+  (chosen ? namedExamples(chosen[1], schemas, direction, components) : []).map(
+    async (example) => ({
+      html: await highlightCode(toJson(example.value), "json", {
+        icons: false,
+        themes: data.config.codeThemes,
+      }),
+      key: example.key,
+      label: example.label,
+    })
+  )
+);
 ---
 
 <section class:list={[level > 2 ? "mt-5" : "mt-8"]}>
@@ -72,4 +99,11 @@ const schema = chosen?.[1]?.schema ?? {};
       schemas={schemas}
     />
   </div>
+  {
+    examplePanels.length > 0 && (
+      <div class="not-prose mt-4">
+        <PanelTabs copy heading="Examples" name={`${name}-examples`} panels={examplePanels} />
+      </div>
+    )
+  }
 </section>

package/src/components/openapi/RequestPanel.astro

@@ -4,27 +4,21 @@ import data from "blume:data";
 import { highlightCode } from "../../markdown/index.ts";
 import {
   type ComponentsLike,
-  responseExample,
+  type MediaLike,
   type SchemaLike,
-  type SpecValue,
   toJson,
 } from "./helpers.ts";
 import type { CustomCodeSample } from "./code-samples.ts";
+import {
+  type ExamplePanel,
+  payloadPanels as payloadExamples,
+  type ResponseLike,
+  responsePanels as responseExamples,
+} from "./example-panels.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
 
-interface MediaTypeLike {
-  schema?: SchemaLike;
-  example?: SpecValue;
-  examples?: SpecValue;
-}
-
-interface ResponseLike {
-  description?: string;
-  content?: Record<string, MediaTypeLike>;
-}
-
 interface Props {
   /** The document's `components`, which `$ref`'d examples resolve against. */
   components?: ComponentsLike;
@@ -34,7 +28,7 @@ interface Props {
    * A webhook's body: the rail shows it as a "Payload" example per media
    * type in place of client code, since the API sends the request.
    */
-  payload?: Record<string, MediaTypeLike>;
+  payload?: Record<string, MediaLike>;
   sample?: RequestSample;
   languages?: SampleLanguage[];
   responses: Record<string, ResponseLike>;
@@ -51,18 +45,26 @@ const {
   schemas,
 } = Astro.props;
 
-/** A media type's example, highlighted, or null when it has none. */
-const highlightExample = async (media: MediaTypeLike, type: string) => {
-  const example = responseExample(media, schemas, components);
-  if (example === undefined || example === null) {
-    return null;
-  }
-  const json = type.includes("json");
-  return highlightCode(
-    json || typeof example !== "string" ? toJson(example) : example,
-    json ? "json" : "text",
-    { icons: false, themes: data.config.codeThemes }
-  );
+/**
+ * One example tab, highlighted. A payload that isn't JSON shows a string
+ * example as written; a response example always reads as JSON.
+ */
+const highlightPanel = async (panel: ExamplePanel, asText: boolean) => {
+  const { value } = panel;
+  const text = asText && typeof value === "string";
+  return {
+    html:
+      value === undefined || value === null
+        ? null
+        : await highlightCode(
+            text ? value : toJson(value),
+            text ? "text" : "json",
+            { icons: false, themes: data.config.codeThemes }
+          ),
+    key: panel.key,
+    label: panel.label,
+    text: panel.text,
+  };
 };
 
 // Hand-written samples carry no `lang` key, so the playground leaves them
@@ -78,12 +80,9 @@ const customPanels = await Promise.all(
   }))
 );
 const payloadPanels = await Promise.all(
-  Object.entries(payload ?? {}).map(async ([type, media]) => ({
-    html: await highlightExample(media, type),
-    key: type,
-    label: type,
-    text: "No example payload.",
-  }))
+  payloadExamples(payload, schemas, components).map((panel) =>
+    highlightPanel(panel, !panel.type.includes("json"))
+  )
 );
 const requestPanels = [
   ...customPanels,
@@ -91,28 +90,10 @@ const requestPanels = [
     ? await languageSamplePanels(languages, sample, data.config.codeThemes)
     : []),
 ];
-
 const responsePanels = await Promise.all(
-  Object.entries(responses).map(async ([status, response]) => {
-    const media =
-      Object.entries(response.content ?? {}).find(([type]) =>
-        type.includes("json")
-      )?.[1] ?? Object.values(response.content ?? {})[0];
-    const example = media ? responseExample(media, schemas, components) : undefined;
-    const html =
-      example === undefined || example === null
-        ? null
-        : await highlightCode(toJson(example), "json", {
-            icons: false,
-            themes: data.config.codeThemes,
-          });
-    return {
-      html,
-      key: status,
-      label: status,
-      text: response.description || "No example response.",
-    };
-  })
+  responseExamples(responses, schemas, components).map((panel) =>
+    highlightPanel(panel, false)
+  )
 );
 ---
 

package/src/components/openapi/example-panels.ts

@@ -0,0 +1,110 @@
+import { namedExamples, responseExample } from "./helpers.ts";
+import type {
+  ComponentsLike,
+  MediaLike,
+  SchemaLike,
+  SpecValue,
+} from "./helpers.ts";
+
+/**
+ * The example tabs of an operation's rail (`RequestPanel.astro`): one per
+ * response status, or per webhook payload media type — and one per named
+ * example where its `examples` map names two or more, labeled by the
+ * example's `summary` (else its key) after the status or media type, so
+ * every recorded example shows, under its name. Values are left for the
+ * component to highlight.
+ */
+
+/** One tab before highlighting. */
+export interface ExamplePanel {
+  key: string;
+  label: string;
+  /** The status or media type the tab is under. */
+  name: string;
+  /** The media type the value is an example of. */
+  type: string;
+  /** The example, or `null`/`undefined` when there's none to show. */
+  value: SpecValue;
+  /** What the tab says when there's no example. */
+  text: string;
+}
+
+/** A response: its description and its body's media types. */
+export interface ResponseLike {
+  description?: string;
+  content?: Record<string, MediaLike>;
+}
+
+/** The media entry a body shows: the first JSON-ish one, else the first. */
+export const preferredMedia = (
+  content?: Record<string, MediaLike>
+): [string, MediaLike] | undefined => {
+  const entries = Object.entries(content ?? {});
+  return entries.find(([type]) => type.includes("json")) ?? entries[0];
+};
+
+/**
+ * The tabs for one media type: each named example, or the one example
+ * `responseExample` gives. Webhook payloads and responses both travel from
+ * the API, so both read like a response.
+ */
+const mediaPanels = (
+  name: string,
+  type: string,
+  media: MediaLike | undefined,
+  text: string,
+  schemas: Record<string, SchemaLike>,
+  components: ComponentsLike | undefined
+): ExamplePanel[] => {
+  const named = media
+    ? namedExamples(media, schemas, "response", components)
+    : [];
+  if (named.length > 0) {
+    return named.map((example) => ({
+      key: `${name}-${example.key}`,
+      label: `${name} · ${example.label}`,
+      name,
+      text,
+      type,
+      value: example.value,
+    }));
+  }
+  return [
+    {
+      key: name,
+      label: name,
+      name,
+      text,
+      type,
+      value: media ? responseExample(media, schemas, components) : undefined,
+    },
+  ];
+};
+
+/** The Response tabs: per status, per named example. */
+export const responsePanels = (
+  responses: Record<string, ResponseLike>,
+  schemas: Record<string, SchemaLike>,
+  components?: ComponentsLike
+): ExamplePanel[] =>
+  Object.entries(responses).flatMap(([status, response]) => {
+    const [type, media] = preferredMedia(response.content) ?? ["", undefined];
+    return mediaPanels(
+      status,
+      type,
+      media,
+      response.description || "No example response.",
+      schemas,
+      components
+    );
+  });
+
+/** A webhook's Payload tabs: per media type, per named example. */
+export const payloadPanels = (
+  payload: Record<string, MediaLike> | undefined,
+  schemas: Record<string, SchemaLike>,
+  components?: ComponentsLike
+): ExamplePanel[] =>
+  Object.entries(payload ?? {}).flatMap(([type, media]) =>
+    mediaPanels(type, type, media, "No example payload.", schemas, components)
+  );

package/src/components/openapi/helpers.ts

@@ -150,7 +150,10 @@ export const soleAllOfMember = (schema: SchemaLike): SchemaLike | undefined =>
 /**
  * Resolve one level of `$ref` against the document's component schemas. A
  * single-member `allOf` wrapper resolves like its member, with the wrapper's
- * own keywords on top: its `description` is about this field.
+ * own keywords on top: its `description` is about this field. So does a
+ * `$ref` with keywords beside it, which OpenAPI 3.1 allows and .NET writes
+ * for every enum-typed property: the `description` beside the `$ref` is the
+ * property's, the referenced one the type's.
  */
 export const resolveSchema = (
   schemas: Record<string, SchemaLike>,
@@ -166,8 +169,10 @@ export const resolveSchema = (
   }
   if (isString(schema.$ref)) {
     const name = REF_PATTERN.exec(schema.$ref)?.groups?.name;
-    if (name && schemas[name]) {
-      return schemas[name];
+    const target = name ? schemas[name] : undefined;
+    if (target) {
+      const { $ref: _ref, ...own } = schema;
+      return Object.keys(own).length > 0 ? { ...target, ...own } : target;
     }
   }
   return schema;
@@ -325,19 +330,129 @@ export const objectProperties = (
   return { properties: [...properties.entries()], required };
 };
 
+/** Which way an example travels: to the API, or back from it. */
+export type ExampleDirection = "request" | "response";
+
+const isRecord = (value: SpecValue): value is Record<string, SpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Keywords whose values are data, not schemas, so never rewritten. */
+const DATA_KEYWORDS = new Set([
+  "const",
+  "default",
+  "enum",
+  "example",
+  "examples",
+]);
+
+/** Keywords beside a `$ref` that give the value an example of its own. */
+const VALUE_KEYWORDS = ["const", "default", "example", "examples"];
+
+/**
+ * A schema as openapi-sampler should read it: each `$ref` with an example
+ * value beside it (`example`, `examples`, `default`, `const`) wrapped as a
+ * single-member `allOf`, so the value is used. The sampler follows a `$ref`
+ * before it looks at anything beside it, which OpenAPI 3.1 allows and .NET
+ * writes, so `{ $ref: Status, example: "active" }` sampled the referenced
+ * enum's first member instead.
+ */
+const sampleable = (schema: SpecValue): SpecValue => {
+  if (Array.isArray(schema)) {
+    return schema.map(sampleable);
+  }
+  if (!isRecord(schema)) {
+    return schema;
+  }
+  const out: Record<string, SpecValue> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    out[key] = DATA_KEYWORDS.has(key) ? value : sampleable(value);
+  }
+  const { $ref: ref, ...own } = out;
+  if (!(isString(ref) && VALUE_KEYWORDS.some((key) => key in own))) {
+    return out;
+  }
+  const members = Array.isArray(own.allOf) ? own.allOf : [];
+  return { ...own, allOf: [{ $ref: ref }, ...members] };
+};
+
+/** {@link sampleable} component schemas, once per document. */
+const sampleableSchemas = new WeakMap<
+  Record<string, SchemaLike>,
+  Record<string, SchemaLike>
+>();
+
+const sampleableComponents = (
+  schemas: Record<string, SchemaLike>
+): Record<string, SchemaLike> => {
+  const cached = sampleableSchemas.get(schemas);
+  if (cached) {
+    return cached;
+  }
+  // SAFETY: rewriting a `$ref` node into an `allOf` wrapper keeps every
+  // entry a schema.
+  const rewritten = sampleable(schemas) as Record<string, SchemaLike>;
+  sampleableSchemas.set(schemas, rewritten);
+  return rewritten;
+};
+
+/**
+ * An example value with the properties that don't travel `direction` left
+ * out, at every depth its schema describes: `readOnly` ones from a request,
+ * which the server sets, and `writeOnly` ones from a response, which it
+ * never returns. openapi-sampler skips those only in the values it builds; a
+ * declared example (a model's `example`, which TypeSpec writes, or a media
+ * type's) keeps them, so a request sample would send the model's `id`. A
+ * property the schema doesn't describe stays as written.
+ */
+export const forDirection = (
+  value: SpecValue,
+  schema: SchemaLike | undefined,
+  schemas: Record<string, SchemaLike>,
+  direction: ExampleDirection
+): SpecValue => {
+  if (!schema) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const { items } = resolveSchema(schemas, schema);
+    return items
+      ? value.map((item) => forDirection(item, items, schemas, direction))
+      : value;
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  const properties = new Map(objectProperties(schema, schemas).properties);
+  const omitted = direction === "request" ? "readOnly" : "writeOnly";
+  const out: Record<string, SpecValue> = {};
+  for (const [name, member] of Object.entries(value)) {
+    const property = properties.get(name);
+    if (
+      property?.[omitted] === true ||
+      resolveSchema(schemas, property)[omitted] === true
+    ) {
+      continue;
+    }
+    out[name] = forDirection(member, property, schemas, direction);
+  }
+  return out;
+};
+
 /**
  * Build a representative example value for a schema via openapi-sampler
  * (Redoc's generator): declared `example`/`const`/`default`/`enum` values
- * win, formats produce realistic placeholders (`email`, `uuid`, `date-time`),
- * and circular `$ref` chains — which keeping refs intact allows — terminate
- * safely. A request sample skips `readOnly` fields (a server-generated field
- * has no place in one); a response sample skips `writeOnly` fields (a
- * password the client sends never comes back) and keeps the `readOnly` ones.
+ * win, a value beside a `$ref` included, formats produce realistic
+ * placeholders (`email`, `uuid`, `date-time`), and circular `$ref` chains —
+ * which keeping refs intact allows — terminate safely. A request sample
+ * leaves out `readOnly` fields (a server-generated field has no place in
+ * one); a response sample leaves out `writeOnly` fields (a password the
+ * client sends never comes back) and keeps the `readOnly` ones. That holds
+ * inside a declared value the sampler copies too (see {@link forDirection}).
  */
 export const exampleValue = (
   schema: SchemaLike | undefined,
   schemas: Record<string, SchemaLike>,
-  direction: "request" | "response" = "request"
+  direction: ExampleDirection = "request"
 ): SpecValue => {
   if (!schema) {
     return null;
@@ -346,11 +461,12 @@ export const exampleValue = (
   try {
     // SAFETY: SchemaLike structurally covers the JSONSchema7 fields the
     // sampler reads, and the sampler only ever assembles JSON values.
-    return sample(
-      schema as Parameters<typeof sample>[0],
+    const value = sample(
+      sampleable(schema) as Parameters<typeof sample>[0],
       { quiet: true, skipReadOnly: !response, skipWriteOnly: response },
-      { components: { schemas } }
+      { components: { schemas: sampleableComponents(schemas) } }
     ) as SpecValue;
+    return forDirection(value, schema, schemas, direction);
   } catch {
     // An unresolvable $ref or malformed schema is a spec problem the schema
     // tables already surface; a sample is best-effort.
@@ -364,9 +480,6 @@ export interface ExampleCarrier {
   examples?: SpecValue;
 }
 
-const isRecord = (value: SpecValue): value is Record<string, SpecValue> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
 /**
  * The example a parameter or media type declares: its `example`, else the
  * first `value` in its `examples` map — inline, or behind a `$ref` to
@@ -398,18 +511,80 @@ export const declaredExample = (
   return undefined;
 };
 
+/** A media type: the schema of a body and the examples it declares. */
+export type MediaLike = ExampleCarrier & { schema?: SchemaLike };
+
+/**
+ * A media type's example for a body travelling `direction`: the declared
+ * one, else a sample built from its schema, with the properties that don't
+ * travel that way left out (see {@link forDirection}).
+ */
+export const mediaExample = (
+  media: MediaLike,
+  schemas: Record<string, SchemaLike>,
+  direction: ExampleDirection,
+  components?: ComponentsLike
+): SpecValue => {
+  const declared = declaredExample(media, components);
+  return declared === undefined
+    ? exampleValue(media.schema, schemas, direction)
+    : forDirection(declared, media.schema, schemas, direction);
+};
+
 /**
  * A response media type's example for the Response panel: the declared one,
  * else a sample built for the response direction (`readOnly` kept,
- * `writeOnly` skipped).
+ * `writeOnly` left out).
  */
 export const responseExample = (
-  media: ExampleCarrier & { schema?: SchemaLike },
+  media: MediaLike,
   schemas: Record<string, SchemaLike>,
   components?: ComponentsLike
-): SpecValue =>
-  declaredExample(media, components) ??
-  exampleValue(media.schema, schemas, "response");
+): SpecValue => mediaExample(media, schemas, "response", components);
+
+/** One of a media type's named examples, as a tab or the Markdown copy shows it. */
+export interface NamedExample {
+  /** The example's key in the `examples` map. */
+  key: string;
+  /** Its `summary`, else its key. */
+  label: string;
+  value: SpecValue;
+}
+
+/**
+ * Every example a media type's `examples` map names, in order, `$ref`s to
+ * `#/components/examples` resolved, each labeled by its `summary` or else
+ * its key, with the properties that don't travel `direction` left out. Empty
+ * unless the map names two or more: Scalar's upgrade files a 3.0 `example`
+ * as the one entry `default`, which is no name to show, and a lone example
+ * is the one {@link mediaExample} already gives.
+ */
+export const namedExamples = (
+  media: MediaLike,
+  schemas: Record<string, SchemaLike>,
+  direction: ExampleDirection,
+  components?: ComponentsLike
+): NamedExample[] => {
+  if (media.example !== undefined || !isRecord(media.examples)) {
+    return [];
+  }
+  const named: NamedExample[] = [];
+  for (const [key, entry] of Object.entries(media.examples)) {
+    const example = isRecord(entry)
+      ? resolveComponentRef(entry, components, "examples")
+      : undefined;
+    if (example?.value === undefined) {
+      continue;
+    }
+    named.push({
+      key,
+      label:
+        isString(example.summary) && example.summary ? example.summary : key,
+      value: forDirection(example.value, media.schema, schemas, direction),
+    });
+  }
+  return named.length > 1 ? named : [];
+};
 
 /** Pretty-print a JSON value for an example/code block. */
 export const toJson = <T>(value: T): string => JSON.stringify(value, null, 2);