@djangocfg/ui-tools 2.1.287 → 2.1.290

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

@@ -3,78 +3,32 @@
 import consola from 'consola';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
-import { ApiEndpoint, OpenApiInfo, OpenApiSchema, SchemaSource, UseOpenApiSchemaReturn } from '../types';
+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;
 
 // Extract endpoints from OpenAPI schema (all methods). ``baseUrl`` is
 // resolved by the caller via ``resolveBaseUrl`` — we just paste it onto
-// the front of each path here.
-const extractEndpoints = (schema: OpenApiSchema, baseUrl: string): ApiEndpoint[] => {
+// 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.
+//
+// ``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 [];
@@ -107,17 +61,32 @@ const extractEndpoints = (schema: OpenApiSchema, baseUrl: string): ApiEndpoint[]
         });
       }
 
-      // 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,
           });
         }
       }
@@ -125,17 +94,20 @@ const extractEndpoints = (schema: OpenApiSchema, baseUrl: string): ApiEndpoint[]
       // 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,
         };
       }
@@ -150,6 +122,7 @@ const extractEndpoints = (schema: OpenApiSchema, baseUrl: string): ApiEndpoint[]
         parameters: parameters.length > 0 ? parameters : undefined,
         requestBody,
         responses: responses.length > 0 ? responses : undefined,
+        schemaId,
       };
 
       endpoints.push(endpoint);
@@ -185,12 +158,24 @@ interface UseOpenApiSchemaProps {
   /** Global base URL override from ``PlaygroundConfig.baseUrl``.
    *  Per-schema ``SchemaSource.baseUrl`` takes precedence over this. */
   baseUrl?: string;
+  /** When ``true`` the hook fetches every schema in ``schemas`` (not just
+   *  the active one) and exposes them via ``schemasData``. Used by the
+   *  ``sections`` grouping mode — the docs column concatenates endpoints
+   *  from every schema, so they all need to be on the client. Default
+   *  is ``false`` to preserve the original lazy behaviour. */
+  preloadAll?: boolean;
+}
+
+interface SchemaLoadState {
+  loading: boolean;
+  error: string | null;
 }
 
 export default function useOpenApiSchema({
   schemas,
   defaultSchemaId,
   baseUrl: configBaseUrl,
+  preloadAll = false,
 }: UseOpenApiSchemaProps): UseOpenApiSchemaReturn {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -200,6 +185,10 @@ export default function useOpenApiSchema({
   const [loadedSchemas, setLoadedSchemas] = useState<Map<string, OpenApiSchema>>(
     new Map()
   );
+  // Per-schema loading/error state for ``preloadAll`` — each schema may
+  // succeed or fail independently, and the UI wants to render partial
+  // results while slow/broken ones are still resolving.
+  const [loadStates, setLoadStates] = useState<Map<string, SchemaLoadState>>(new Map());
 
   const currentSchema = useMemo(
     () => schemas.find((s) => s.id === currentSchemaId) || null,
@@ -233,8 +222,11 @@ export default function useOpenApiSchema({
   );
 
   const endpoints = useMemo(
-    () => (dereferencedSchema ? extractEndpoints(dereferencedSchema, resolvedBaseUrl) : []),
-    [dereferencedSchema, resolvedBaseUrl]
+    () =>
+      dereferencedSchema
+        ? extractEndpoints(dereferencedSchema, resolvedBaseUrl, currentSchemaId, currentOpenApiSchema ?? undefined)
+        : [],
+    [dereferencedSchema, resolvedBaseUrl, currentSchemaId, currentOpenApiSchema]
   );
 
   const categories = useMemo(() => getCategories(endpoints), [endpoints]);
@@ -250,8 +242,9 @@ export default function useOpenApiSchema({
     };
   }, [currentOpenApiSchema]);
 
-  // Load schema when current schema changes
+  // Load schema when current schema changes (single-schema mode)
   useEffect(() => {
+    if (preloadAll) return;
     if (!currentSchema) return;
 
     // Skip if already loaded
@@ -274,7 +267,103 @@ export default function useOpenApiSchema({
         setError(err instanceof Error ? err.message : 'Failed to load schema');
         setLoading(false);
       });
-  }, [currentSchema, loadedSchemas]);
+  }, [currentSchema, loadedSchemas, preloadAll]);
+
+  // Preload every schema (sections-grouping mode). Each schema is fetched
+  // independently — a slow or broken source doesn't block the rest.
+  useEffect(() => {
+    if (!preloadAll) return;
+    if (schemas.length === 0) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    const pending = schemas.filter((s) => !loadedSchemas.has(s.id));
+    if (pending.length === 0) {
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    setLoadStates((prev) => {
+      const next = new Map(prev);
+      for (const s of pending) next.set(s.id, { loading: true, error: null });
+      return next;
+    });
+
+    Promise.allSettled(
+      pending.map((s) =>
+        fetchSchema(s.url).then((schema) => ({ id: s.id, name: s.name, schema })),
+      ),
+    ).then((results) => {
+      if (cancelled) return;
+
+      setLoadedSchemas((prev) => {
+        const next = new Map(prev);
+        for (const r of results) {
+          if (r.status === 'fulfilled') {
+            next.set(r.value.id, r.value.schema);
+            consola.success(`Schema loaded: ${r.value.name}`);
+          }
+        }
+        return next;
+      });
+
+      setLoadStates((prev) => {
+        const next = new Map(prev);
+        results.forEach((r, i) => {
+          const src = pending[i]!;
+          if (r.status === 'fulfilled') {
+            next.set(src.id, { loading: false, error: null });
+          } else {
+            const msg = r.reason instanceof Error ? r.reason.message : 'Failed to load schema';
+            consola.error(`Error loading schema from ${src.url}:`, r.reason);
+            next.set(src.id, { loading: false, error: msg });
+          }
+        });
+        return next;
+      });
+
+      setLoading(false);
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [preloadAll, schemas, loadedSchemas]);
+
+  const schemasData = useMemo<LoadedSchemaEntry[]>(() => {
+    if (!preloadAll) return [];
+    return schemas.map((src) => {
+      const raw = loadedSchemas.get(src.id) ?? null;
+      const deref = raw ? dereferenceSchema(raw) : null;
+      const resolved = resolveBaseUrl({
+        schemaSource: src.baseUrl,
+        config: configBaseUrl,
+        fromServers: raw?.servers?.[0]?.url,
+      });
+      const info: OpenApiInfo | null = raw?.info
+        ? {
+            title: raw.info.title,
+            version: raw.info.version,
+            description: raw.info.description,
+            servers: raw.servers,
+          }
+        : null;
+      const eps = deref ? extractEndpoints(deref, resolved, src.id, raw ?? undefined) : [];
+      const state = loadStates.get(src.id) ?? { loading: !raw, error: null };
+      return {
+        source: src,
+        info,
+        rawSchema: raw,
+        endpoints: eps,
+        resolvedBaseUrl: resolved || undefined,
+        loading: state.loading,
+        error: state.error,
+      };
+    });
+  }, [preloadAll, schemas, loadedSchemas, loadStates, configBaseUrl]);
 
   const setCurrentSchema = useCallback((schemaId: string) => {
     setCurrentSchemaId(schemaId);
@@ -321,5 +410,6 @@ export default function useOpenApiSchema({
     resolvedBaseUrl: resolvedBaseUrl || undefined,
     setCurrentSchema,
     refresh,
+    schemasData,
   };
 }

package/src/tools/OpenapiViewer/types.ts

@@ -19,6 +19,10 @@ export interface ApiEndpoint {
   name: string;
   method: string;
   path: string;
+  /** ID of the schema this endpoint was extracted from. Populated whenever
+   *  endpoints from multiple schemas coexist (``sections`` grouping), so
+   *  sidebar grouping, anchors and URL sync can all tell them apart. */
+  schemaId?: string;
   /** Short human label from OpenAPI ``operation.summary``. Empty when
    *  the spec provides none. Prefer this for sidebar rows and breadcrumbs. */
   summary: string;
@@ -43,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;
   }>;
 }
 
@@ -92,6 +106,20 @@ export interface PlaygroundConfig {
    *  a spinner instead of "no keys yet". */
   apiKeys?: ApiKey[];
   apiKeysLoading?: boolean;
+  /** How multiple schemas are presented in the sidebar.
+   *  - ``'selector'`` (default): a Combobox switches between schemas, the
+   *    docs column shows endpoints of the active schema only.
+   *  - ``'sections'``: the Combobox is hidden and every schema becomes a
+   *    top-level heading in the sidebar, with endpoints of all schemas
+   *    rendered back-to-back in the docs column. Scrollspy picks the
+   *    active schema based on what's visible. */
+  schemaGrouping?: 'selector' | 'sections';
+  /** Optional URL-hash sync. When enabled, the viewer reads/writes
+   *  ``#<schemaId>/<anchor>`` on the browser location. Falsy value (the
+   *  default) keeps the viewer hash-free. Set to an object with
+   *  ``{ enabled: true }`` to opt in; future fields (e.g. a custom
+   *  adapter) stay backwards compatible. */
+  urlSync?: boolean | { enabled: boolean };
 }
 
 // Playground state types
@@ -190,6 +218,19 @@ export interface OpenApiInfo {
   servers?: Array<{ url: string; description?: string }>;
 }
 
+/** Per-schema snapshot used by the ``sections`` grouping mode. Mirrors the
+ *  fields that ``UseOpenApiSchemaReturn`` exposes for the active schema,
+ *  but repeated for every loaded schema. */
+export interface LoadedSchemaEntry {
+  source: SchemaSource;
+  info: OpenApiInfo | null;
+  rawSchema: OpenApiSchema | null;
+  endpoints: ApiEndpoint[];
+  resolvedBaseUrl: string | undefined;
+  loading: boolean;
+  error: string | null;
+}
+
 // Hook return types
 export interface UseOpenApiSchemaReturn {
   loading: boolean;
@@ -208,4 +249,8 @@ export interface UseOpenApiSchemaReturn {
   resolvedBaseUrl: string | undefined;
   setCurrentSchema: (schemaId: string) => void;
   refresh: () => void;
-} 
+  /** Populated only when the hook was called with ``preloadAll: true``
+   *  (``sections`` grouping mode). One entry per schema source, in the
+   *  same order as ``schemas``. */
+  schemasData: LoadedSchemaEntry[];
+}