@djangocfg/ui-tools 2.1.289 → 2.1.291

package/src/tools/OpenapiViewer/hooks/useOpenApiSchema.ts

@@ -4,69 +4,11 @@ import consola from 'consola';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
 import { ApiEndpoint, LoadedSchemaEntry, OpenApiInfo, OpenApiSchema, SchemaSource, UseOpenApiSchemaReturn } from '../types';
+import { sampleSchemaJson } from '../utils/sampler';
 import { dereferenceSchema } from '../utils/schemaExport';
 import { joinUrl, resolveBaseUrl } from '../utils/url';
 
-// ─── JSON Schema → example value ──────────────────────────────────────────────
-
-type JsonSchemaNode = Record<string, unknown> & {
-  type?: string;
-  properties?: Record<string, JsonSchemaNode>;
-  required?: string[];
-  items?: JsonSchemaNode;
-  enum?: unknown[];
-  example?: unknown;
-  default?: unknown;
-  format?: string;
-};
-
-/** Walk a JSON Schema and build a realistic-looking example value. */
-function exampleFromSchema(schema: JsonSchemaNode | undefined, depth = 0): unknown {
-  if (!schema || depth > 8) return null;
-
-  // Respect schema-provided examples first — no need to invent a value
-  // when the spec author already did the work.
-  if (schema.example !== undefined) return schema.example;
-  if (schema.default !== undefined) return schema.default;
-  if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
-
-  switch (schema.type) {
-    case 'object': {
-      const out: Record<string, unknown> = {};
-      const props = schema.properties ?? {};
-      for (const [k, v] of Object.entries(props)) {
-        out[k] = exampleFromSchema(v, depth + 1);
-      }
-      return out;
-    }
-    case 'array':
-      return [exampleFromSchema(schema.items, depth + 1)];
-    case 'integer':
-    case 'number':
-      return 0;
-    case 'boolean':
-      return false;
-    case 'string':
-      if (schema.format === 'date-time') return new Date().toISOString();
-      if (schema.format === 'date') return new Date().toISOString().slice(0, 10);
-      if (schema.format === 'email') return 'user@example.com';
-      if (schema.format === 'uri' || schema.format === 'url') return 'https://example.com';
-      if (schema.format === 'uuid') return '00000000-0000-0000-0000-000000000000';
-      return '';
-    default:
-      // No type (or composed schema like allOf/oneOf we don't unpack) —
-      // fall back to an empty object rather than ``null`` so the resulting
-      // JSON is still valid-looking.
-      if (schema.properties) {
-        const out: Record<string, unknown> = {};
-        for (const [k, v] of Object.entries(schema.properties)) {
-          out[k] = exampleFromSchema(v, depth + 1);
-        }
-        return out;
-      }
-      return null;
-  }
-}
+type JsonSchemaNode = Record<string, unknown>;
 
 // HTTP methods to extract from OpenAPI schema
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const;
@@ -76,7 +18,17 @@ const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const;
 // the front of each path here. ``schemaId`` is tagged onto every
 // endpoint so downstream consumers (sections-mode sidebar, anchors, URL
 // sync) can correlate endpoints back to their source schema.
-const extractEndpoints = (schema: OpenApiSchema, baseUrl: string, schemaId?: string): ApiEndpoint[] => {
+//
+// ``specRoot`` is the raw, un-dereferenced schema — passed to
+// ``openapi-sampler`` so it can resolve any ``$ref`` nodes our own
+// ``dereferenceSchema`` left behind (depth-limited, external, or
+// circular). Without it the sampler throws on deep ref chains.
+const extractEndpoints = (
+  schema: OpenApiSchema,
+  baseUrl: string,
+  schemaId?: string,
+  specRoot?: OpenApiSchema,
+): ApiEndpoint[] => {
   const endpoints: ApiEndpoint[] = [];
 
   if (!schema.paths) return [];
@@ -109,17 +61,32 @@ const extractEndpoints = (schema: OpenApiSchema, baseUrl: string, schemaId?: str
         });
       }
 
-      // Collect responses
-      const responses: Array<{
-        code: string;
-        description: string;
-      }> = [];
+      // Collect responses. We also extract the ``application/json``
+      // schema (preferring it, falling back to whatever media type is
+      // present) and generate a sampled example — the docs layout
+      // renders it as a collapsible "Example response" block under the
+      // status-code table. ``writeOnly`` fields are skipped so secrets
+      // declared ``writeOnly: true`` don't leak into response samples.
+      const responses: NonNullable<ApiEndpoint['responses']> = [];
 
       if (op.responses) {
         for (const [code, response] of Object.entries(op.responses)) {
+          const respContent = (response as any).content as Record<string, any> | undefined;
+          const contentKeys = respContent ? Object.keys(respContent) : [];
+          const chosenContentType = respContent?.['application/json']
+            ? 'application/json'
+            : contentKeys[0];
+          const chosen = chosenContentType ? respContent?.[chosenContentType] : undefined;
+          const respSchema = chosen?.schema as JsonSchemaNode | undefined;
+
           responses.push({
             code,
             description: (response as any).description || `Response ${code}`,
+            contentType: chosenContentType,
+            schema: respSchema,
+            example: respSchema
+              ? sampleSchemaJson(respSchema, { skipWriteOnly: true }, specRoot)
+              : undefined,
           });
         }
       }
@@ -127,17 +94,20 @@ const extractEndpoints = (schema: OpenApiSchema, baseUrl: string, schemaId?: str
       // Extract request body info — keep the dereferenced schema so
       // downstream UI can render a fields table and generate a starter
       // example instead of showing an opaque ``object`` / ``array`` tag.
+      // ``readOnly`` fields are skipped: the body is what the client
+      // *sends*, so server-owned fields (id, created_at, …) must not
+      // pre-fill the editor.
       let requestBody: ApiEndpoint['requestBody'];
       if (op.requestBody) {
         const content = op.requestBody.content;
         const mediaType = content?.['application/json'] || content?.[Object.keys(content || {})[0]];
         const rawSchema = mediaType?.schema as JsonSchemaNode | undefined;
         requestBody = {
-          type: rawSchema?.type || 'object',
+          type: (rawSchema?.type as string | undefined) || 'object',
           description: op.requestBody.description,
           schema: rawSchema,
           example: rawSchema
-            ? JSON.stringify(exampleFromSchema(rawSchema), null, 2)
+            ? sampleSchemaJson(rawSchema, { skipReadOnly: true }, specRoot)
             : undefined,
         };
       }
@@ -254,9 +224,9 @@ export default function useOpenApiSchema({
   const endpoints = useMemo(
     () =>
       dereferencedSchema
-        ? extractEndpoints(dereferencedSchema, resolvedBaseUrl, currentSchemaId)
+        ? extractEndpoints(dereferencedSchema, resolvedBaseUrl, currentSchemaId, currentOpenApiSchema ?? undefined)
         : [],
-    [dereferencedSchema, resolvedBaseUrl, currentSchemaId]
+    [dereferencedSchema, resolvedBaseUrl, currentSchemaId, currentOpenApiSchema]
   );
 
   const categories = useMemo(() => getCategories(endpoints), [endpoints]);
@@ -381,7 +351,7 @@ export default function useOpenApiSchema({
             servers: raw.servers,
           }
         : null;
-      const eps = deref ? extractEndpoints(deref, resolved, src.id) : [];
+      const eps = deref ? extractEndpoints(deref, resolved, src.id, raw ?? undefined) : [];
       const state = loadStates.get(src.id) ?? { loading: !raw, error: null };
       return {
         source: src,

package/src/tools/OpenapiViewer/types.ts

@@ -47,6 +47,16 @@ export interface ApiEndpoint {
   responses?: Array<{
     code: string;
     description: string;
+    /** Media type the schema is sourced from (e.g. ``application/json``).
+     *  ``undefined`` when the response advertises no body. */
+    contentType?: string;
+    /** Dereferenced JSON Schema for the response body. Used by the docs
+     *  layout to render a sampled example under the status-code table. */
+    schema?: Record<string, unknown>;
+    /** Pre-generated example JSON (sampled via ``openapi-sampler``).
+     *  ``undefined`` when the response has no schema or sampling failed
+     *  — the UI conditionally hides the "Example" block in that case. */
+    example?: string;
   }>;
 }
 

package/src/tools/OpenapiViewer/utils/codeSamples.ts

@@ -0,0 +1,287 @@
+/**
+ * Code sample generation.
+ *
+ * In-house, browser-safe generator for a small catalogue of languages
+ * (curl / fetch / Node axios / Python requests / Go / PHP / Ruby /
+ * Java OkHttp). We used to wrap Kong's ``httpsnippet`` here but it is
+ * Node-only — the bundle referenced ``global`` / ``stream`` /
+ * ``string_decoder`` and crashed in Vite dev. Writing our own keeps the
+ * chunk small (a few kB vs ~1.5 MB) and avoids runtime polyfills.
+ *
+ * Adding more targets later is one function plus a row in the catalogue.
+ */
+
+import type { HarRequest } from './operationToHar';
+
+// Prism language ids used by ``prism-react-renderer``. ``bash``,
+// ``ruby``, ``java`` and ``php`` aren't in the library's default
+// bundle, but our ``registerPrismLanguages`` module pulls their
+// grammars from ``prismjs`` at load time so they work as first-class
+// languages here.
+export const CODE_SAMPLE_TARGETS = [
+    { id: 'curl', label: 'cURL', prism: 'bash' },
+    { id: 'fetch', label: 'JavaScript', prism: 'javascript' },
+    { id: 'axios', label: 'Node (axios)', prism: 'javascript' },
+    { id: 'python', label: 'Python', prism: 'python' },
+    { id: 'go', label: 'Go', prism: 'go' },
+    { id: 'php', label: 'PHP', prism: 'php' },
+    { id: 'ruby', label: 'Ruby', prism: 'ruby' },
+    { id: 'java', label: 'Java', prism: 'java' },
+] as const;
+
+export type CodeSampleTargetId = typeof CODE_SAMPLE_TARGETS[number]['id'];
+
+// ─── Body literal helpers ─────────────────────────────────────────────────────
+//
+// Pre-formatted JSON bodies (``JSON.stringify(value, null, 2)``) carry
+// real newlines that we want the snippet to preserve — a one-line
+// escaped string like ``"{\n  \"id\": 10,\n …}"`` reads as a wall of
+// escape sequences. Each helper below returns a multi-line string
+// literal in the target language's native syntax so the snippet reads
+// like hand-written code.
+
+/** Go raw string literal — uses backticks. Falls back to a double-
+ *  quoted escaped literal when the body itself contains a backtick. */
+function goRawString(s: string): string {
+    return s.includes('`') ? JSON.stringify(s) : `\`${s}\``;
+}
+
+/** Python triple-quoted string — uses ``"""``. Falls back to escaped
+ *  form when the body already contains that sequence. */
+function pythonTripleQuote(s: string): string {
+    return s.includes('"""') ? JSON.stringify(s) : `"""${s}"""`;
+}
+
+/** Ruby squiggly heredoc — ``<<~JSON`` style strips common leading
+ *  whitespace. Safe unless the body literally contains ``JSON`` on a
+ *  line by itself, which is vanishingly rare. */
+function rubyHeredoc(s: string): string {
+    return `<<~JSON\n${s}\nJSON`;
+}
+
+/** PHP heredoc — ``<<<JSON`` style. Same caveat as Ruby's. Trailing
+ *  ``JSON;`` must sit at column 0 (enforced by this template). */
+function phpHeredoc(s: string): string {
+    return `<<<JSON\n${s}\nJSON`;
+}
+
+/** Java 15+ text block — ``"""``. Falls back to an escaped literal
+ *  when the body contains that sequence. */
+function javaTextBlock(s: string): string {
+    if (s.includes('"""')) return JSON.stringify(s);
+    // Text blocks need the opening ``"""`` on its own line — the
+    // parser strips the newline that immediately follows the delimiter.
+    return `"""\n${s}\n"""`;
+}
+
+function fullUrl(har: HarRequest): string {
+    if (!har.queryString.length) return har.url;
+    const qs = har.queryString
+        .map((p) => `${encodeURIComponent(p.name)}=${encodeURIComponent(p.value)}`)
+        .join('&');
+    const sep = har.url.includes('?') ? '&' : '?';
+    return `${har.url}${sep}${qs}`;
+}
+
+function shellEscape(value: string): string {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function renderCurl(har: HarRequest): string {
+    const lines: string[] = [`curl -X ${har.method} ${shellEscape(fullUrl(har))}`];
+    for (const h of har.headers) {
+        lines.push(`  -H ${shellEscape(`${h.name}: ${h.value}`)}`);
+    }
+    if (har.postData?.text) {
+        lines.push(`  -d ${shellEscape(har.postData.text)}`);
+    }
+    return lines.join(' \\\n');
+}
+
+function jsHeadersLiteral(har: HarRequest, indent: string): string {
+    if (!har.headers.length) return '{}';
+    const entries = har.headers
+        .map((h) => `${indent}  ${JSON.stringify(h.name)}: ${JSON.stringify(h.value)}`)
+        .join(',\n');
+    return `{\n${entries},\n${indent}}`;
+}
+
+/** JS template literal — backtick string that preserves newlines and
+ *  escapes backticks / ``${`` sequences. Makes multi-line JSON body
+ *  readable inside the fetch() options. */
+function jsTemplateLiteral(s: string): string {
+    if (/[`$]/.test(s)) return JSON.stringify(s);
+    return `\`${s}\``;
+}
+
+function renderFetch(har: HarRequest): string {
+    const url = fullUrl(har);
+    const options: string[] = [`  method: ${JSON.stringify(har.method)}`];
+    if (har.headers.length) {
+        options.push(`  headers: ${jsHeadersLiteral(har, '  ')}`);
+    }
+    if (har.postData?.text) {
+        options.push(`  body: ${jsTemplateLiteral(har.postData.text)}`);
+    }
+    return `const response = await fetch(${JSON.stringify(url)}, {\n${options.join(',\n')},\n});\nconst data = await response.json();`;
+}
+
+function renderAxios(har: HarRequest): string {
+    const url = fullUrl(har);
+    const config: string[] = [
+        `  method: ${JSON.stringify(har.method.toLowerCase())}`,
+        `  url: ${JSON.stringify(url)}`,
+    ];
+    if (har.headers.length) {
+        config.push(`  headers: ${jsHeadersLiteral(har, '  ')}`);
+    }
+    if (har.postData?.text) {
+        // Axios auto-serializes objects; we pass the raw JSON string as data.
+        config.push(`  data: ${har.postData.text}`);
+    }
+    return `import axios from 'axios';\n\nconst { data } = await axios({\n${config.join(',\n')},\n});`;
+}
+
+function renderPython(har: HarRequest): string {
+    const lines: string[] = [`import requests`, ``];
+    lines.push(`url = ${JSON.stringify(fullUrl(har))}`);
+    if (har.headers.length) {
+        const headerEntries = har.headers
+            .map((h) => `    ${JSON.stringify(h.name)}: ${JSON.stringify(h.value)}`)
+            .join(',\n');
+        lines.push(`headers = {\n${headerEntries},\n}`);
+    }
+    if (har.postData?.text) {
+        // ``json=payload`` on ``requests`` expects a Python object, not
+        // a JSON string — so we leave the body as a raw dict literal
+        // (which Python parses identically to the JSON source for the
+        // shapes we generate). No wrapping helper needed here.
+        lines.push(`payload = ${har.postData.text}`);
+    }
+    const args = [`url`];
+    if (har.headers.length) args.push(`headers=headers`);
+    if (har.postData?.text) args.push(`json=payload`);
+    lines.push(``, `response = requests.${har.method.toLowerCase()}(${args.join(', ')})`);
+    lines.push(`data = response.json()`);
+    return lines.join('\n');
+}
+
+function renderGo(har: HarRequest): string {
+    const url = fullUrl(har);
+    const lines: string[] = [
+        `package main`,
+        ``,
+        `import (`,
+        `    "fmt"`,
+        `    "io"`,
+    ];
+    if (har.postData?.text) lines.push(`    "strings"`);
+    lines.push(`    "net/http"`);
+    lines.push(`)`, ``, `func main() {`);
+    if (har.postData?.text) {
+        lines.push(`    payload := strings.NewReader(${goRawString(har.postData.text)})`);
+        lines.push(`    req, _ := http.NewRequest(${JSON.stringify(har.method)}, ${JSON.stringify(url)}, payload)`);
+    } else {
+        lines.push(`    req, _ := http.NewRequest(${JSON.stringify(har.method)}, ${JSON.stringify(url)}, nil)`);
+    }
+    for (const h of har.headers) {
+        lines.push(`    req.Header.Add(${JSON.stringify(h.name)}, ${JSON.stringify(h.value)})`);
+    }
+    lines.push(
+        ``,
+        `    res, _ := http.DefaultClient.Do(req)`,
+        `    defer res.Body.Close()`,
+        `    body, _ := io.ReadAll(res.Body)`,
+        `    fmt.Println(string(body))`,
+        `}`,
+    );
+    return lines.join('\n');
+}
+
+function renderPhp(har: HarRequest): string {
+    const lines: string[] = [`<?php`, ``, `$curl = curl_init();`, ``, `curl_setopt_array($curl, [`];
+    lines.push(`    CURLOPT_URL => ${JSON.stringify(fullUrl(har))},`);
+    lines.push(`    CURLOPT_RETURNTRANSFER => true,`);
+    lines.push(`    CURLOPT_CUSTOMREQUEST => ${JSON.stringify(har.method)},`);
+    if (har.postData?.text) {
+        lines.push(`    CURLOPT_POSTFIELDS => ${phpHeredoc(har.postData.text)},`);
+    }
+    if (har.headers.length) {
+        const headerList = har.headers
+            .map((h) => `        ${JSON.stringify(`${h.name}: ${h.value}`)}`)
+            .join(',\n');
+        lines.push(`    CURLOPT_HTTPHEADER => [\n${headerList},\n    ],`);
+    }
+    lines.push(`]);`, ``, `$response = curl_exec($curl);`, `curl_close($curl);`, `echo $response;`);
+    return lines.join('\n');
+}
+
+function renderRuby(har: HarRequest): string {
+    const lines: string[] = [
+        `require 'net/http'`,
+        `require 'uri'`,
+        `require 'json'`,
+        ``,
+        `uri = URI(${JSON.stringify(fullUrl(har))})`,
+        `http = Net::HTTP.new(uri.host, uri.port)`,
+        `http.use_ssl = uri.scheme == 'https'`,
+        ``,
+    ];
+    const methodClass = har.method.charAt(0) + har.method.slice(1).toLowerCase();
+    lines.push(`request = Net::HTTP::${methodClass}.new(uri)`);
+    for (const h of har.headers) {
+        lines.push(`request[${JSON.stringify(h.name)}] = ${JSON.stringify(h.value)}`);
+    }
+    if (har.postData?.text) {
+        lines.push(`request.body = ${rubyHeredoc(har.postData.text)}`);
+    }
+    lines.push(``, `response = http.request(request)`, `puts response.body`);
+    return lines.join('\n');
+}
+
+function renderJava(har: HarRequest): string {
+    const lines: string[] = [
+        `OkHttpClient client = new OkHttpClient();`,
+        ``,
+    ];
+    if (har.postData?.text) {
+        lines.push(
+            `MediaType mediaType = MediaType.parse("application/json");`,
+            `RequestBody body = RequestBody.create(mediaType, ${javaTextBlock(har.postData.text)});`,
+            ``,
+        );
+    }
+    lines.push(`Request request = new Request.Builder()`);
+    lines.push(`  .url(${JSON.stringify(fullUrl(har))})`);
+    if (har.postData?.text) {
+        lines.push(`  .method(${JSON.stringify(har.method)}, body)`);
+    } else {
+        lines.push(`  .method(${JSON.stringify(har.method)}, null)`);
+    }
+    for (const h of har.headers) {
+        lines.push(`  .addHeader(${JSON.stringify(h.name)}, ${JSON.stringify(h.value)})`);
+    }
+    lines.push(`  .build();`, ``, `Response response = client.newCall(request).execute();`);
+    return lines.join('\n');
+}
+
+const RENDERERS: Record<CodeSampleTargetId, (har: HarRequest) => string> = {
+    curl: renderCurl,
+    fetch: renderFetch,
+    axios: renderAxios,
+    python: renderPython,
+    go: renderGo,
+    php: renderPhp,
+    ruby: renderRuby,
+    java: renderJava,
+};
+
+export function renderSnippet(har: HarRequest, targetId: CodeSampleTargetId): string | null {
+    const renderer = RENDERERS[targetId];
+    if (!renderer) return null;
+    try {
+        return renderer(har);
+    } catch {
+        return null;
+    }
+}

package/src/tools/OpenapiViewer/utils/index.ts

@@ -5,7 +5,10 @@
  */
 
 export * from './apiKeyManager';
+export * from './codeSamples';
+export * from './operationToHar';
 export * from './versionManager';
 export * from './formatters';
+export * from './sampler';
 export * from './schemaExport';
 export * from './url';

package/src/tools/OpenapiViewer/utils/operationToHar.ts

@@ -0,0 +1,119 @@
+/**
+ * OpenAPI endpoint → HAR request.
+ *
+ * Our in-house code-sample renderers consume a HAR 1.2-shaped request.
+ * This module shapes an ``ApiEndpoint`` + user-provided parameter
+ * values into that form — path substitution, query-string assembly,
+ * header inference, body formatting.
+ *
+ * We keep the HAR intermediate (rather than a bespoke type) so the
+ * renderers match well-known HAR semantics and stay easy to extend.
+ */
+
+import type { ApiEndpoint } from '../types';
+
+/** HAR 1.2 request subset that our renderers consume. We don't ship
+ *  the full HAR type surface — just the fields that snippet generators
+ *  actually read. */
+export interface HarRequest {
+    method: string;
+    url: string;
+    httpVersion: string;
+    headers: Array<{ name: string; value: string }>;
+    queryString: Array<{ name: string; value: string }>;
+    cookies: Array<{ name: string; value: string }>;
+    headersSize: number;
+    bodySize: number;
+    postData?: {
+        mimeType: string;
+        text: string;
+    };
+}
+
+export interface BuildHarInput {
+    endpoint: ApiEndpoint;
+    /** Raw body string — whatever the user typed in the playground or
+     *  the pre-sampled example. Passed through verbatim; the caller
+     *  decides the content shape. */
+    body?: string;
+    /** Path-param + query-param values, keyed by name. We look up each
+     *  parameter on ``endpoint`` to decide whether it slots into the
+     *  path or the query string. */
+    parameters?: Record<string, string>;
+    /** Extra headers to merge in (e.g. ``X-API-Key``, ``Authorization``).
+     *  Later entries with the same name override earlier ones. */
+    headers?: Record<string, string>;
+    /** Override the request URL's base. When absent we use
+     *  ``endpoint.path`` as-is (extractor already prepended base URL). */
+    baseUrl?: string;
+}
+
+/** Split a template path into path vs query. Substitutes ``{id}``-style
+ *  placeholders using the provided parameter map; unused entries flow
+ *  into the query string. */
+function buildUrl(
+    endpoint: ApiEndpoint,
+    parameters: Record<string, string>,
+    baseUrl?: string,
+): { url: string; queryString: HarRequest['queryString'] } {
+    const pathParamNames = new Set(
+        (endpoint.parameters ?? [])
+            .filter((p) => endpoint.path.includes(`{${p.name}}`))
+            .map((p) => p.name),
+    );
+
+    let path = endpoint.path;
+    for (const name of pathParamNames) {
+        const value = parameters[name] ?? `{${name}}`;
+        path = path.replaceAll(`{${name}}`, encodeURIComponent(value));
+    }
+
+    const queryString: HarRequest['queryString'] = [];
+    for (const param of endpoint.parameters ?? []) {
+        if (pathParamNames.has(param.name)) continue;
+        const value = parameters[param.name];
+        if (value === undefined || value === '') continue;
+        queryString.push({ name: param.name, value });
+    }
+
+    const url = baseUrl ? `${baseUrl.replace(/\/+$/, '')}${path.startsWith('/') ? path : `/${path}`}` : path;
+    return { url, queryString };
+}
+
+/** Build a HAR 1.2 request from an API endpoint + current form values. */
+export function buildHarRequest(input: BuildHarInput): HarRequest {
+    const { endpoint, body, parameters = {}, headers = {}, baseUrl } = input;
+    const { url, queryString } = buildUrl(endpoint, parameters, baseUrl);
+
+    const hasBody = Boolean(body && body.trim().length > 0);
+    const bodyMime = hasBody
+        ? 'application/json'
+        : undefined;
+
+    // Merge headers. Caller wins, but we default Content-Type for bodies
+    // and Accept for JSON endpoints — snippet consumers expect these.
+    const mergedHeaders: Record<string, string> = {};
+    if (hasBody && bodyMime) mergedHeaders['Content-Type'] = bodyMime;
+    mergedHeaders['Accept'] = 'application/json';
+    for (const [k, v] of Object.entries(headers)) {
+        if (v === undefined || v === '') continue;
+        mergedHeaders[k] = v;
+    }
+
+    const har: HarRequest = {
+        method: endpoint.method.toUpperCase(),
+        url,
+        httpVersion: 'HTTP/1.1',
+        headers: Object.entries(mergedHeaders).map(([name, value]) => ({ name, value })),
+        queryString,
+        cookies: [],
+        headersSize: -1,
+        bodySize: hasBody ? new TextEncoder().encode(body!).length : 0,
+    };
+
+    if (hasBody && bodyMime) {
+        har.postData = { mimeType: bodyMime, text: body! };
+    }
+
+    return har;
+}

package/src/tools/OpenapiViewer/utils/sampler.ts

@@ -0,0 +1,72 @@
+/**
+ * JSON Schema → example JSON.
+ *
+ * Thin wrapper over ``openapi-sampler`` (by Redocly — same library Redoc
+ * uses internally). Picks deterministic, realistic values from a
+ * dereferenced schema: honours ``const`` / ``examples`` / ``enum`` /
+ * ``default``, unpacks ``allOf`` / ``oneOf`` / ``anyOf``, respects
+ * string ``format`` (email/uuid/date-time/…).
+ *
+ * Replaces the previous hand-rolled ``exampleFromSchema`` — stricter on
+ * spec semantics and cheaper to maintain.
+ */
+
+import consola from 'consola';
+import { sample as openapiSample } from 'openapi-sampler';
+
+type JsonSchemaLike = Record<string, unknown>;
+
+export interface SampleOptions {
+    /** Skip properties marked ``readOnly`` — useful when the body will
+     *  be sent in a request (request body editor). Default ``false``. */
+    skipReadOnly?: boolean;
+    /** Skip properties marked ``writeOnly`` — useful when rendering a
+     *  response body (passwords etc. must not leak). Default ``false``. */
+    skipWriteOnly?: boolean;
+    /** Skip non-required properties. Rarely useful for a viewer — we
+     *  want to show the full shape. Default ``false``. */
+    skipNonRequired?: boolean;
+}
+
+/** Sample a JSON schema into a plain value. Returns ``null`` on failure
+ *  (malformed schema, circular refs the sampler can't unwind) so the
+ *  caller can show "no example" instead of crashing the page.
+ *
+ *  ``spec`` must be the root OpenAPI document whenever ``schema`` may
+ *  contain ``$ref`` nodes — ``openapi-sampler`` walks the tree and
+ *  resolves refs against it. Our own ``dereferenceSchema`` only inlines
+ *  refs up to a depth limit; anything deeper comes through here as a
+ *  live ``$ref`` and the sampler throws if ``spec`` is missing. */
+export function sampleSchema(
+    schema: JsonSchemaLike | undefined,
+    options: SampleOptions = {},
+    spec?: unknown,
+): unknown {
+    if (!schema) return null;
+    try {
+        return openapiSample(schema as never, options, spec as never);
+    } catch (err) {
+        // Sampler failures used to be silent, which meant "no example"
+        // in the UI looked like a missing spec entry. Log so we can see
+        // the real cause in dev (circular refs, missing type, etc.).
+        consola.warn('[OpenapiViewer] sampleSchema failed:', err, { schema });
+        return null;
+    }
+}
+
+/** Same as ``sampleSchema`` but returns a pre-stringified JSON payload
+ *  ready to drop into a textarea / code block. Returns ``undefined``
+ *  when sampling fails so the UI can conditionally hide the example. */
+export function sampleSchemaJson(
+    schema: JsonSchemaLike | undefined,
+    options: SampleOptions = {},
+    spec?: unknown,
+): string | undefined {
+    const value = sampleSchema(schema, options, spec);
+    if (value === null || value === undefined) return undefined;
+    try {
+        return JSON.stringify(value, null, 2);
+    } catch {
+        return undefined;
+    }
+}