docusaurus-theme-openapi-docs 0.0.0-1268 → 0.0.0-1294

package/lib/markdown/schema.js

@@ -42,13 +42,36 @@ function getTypeFromSchema(schema) {
     }
     return undefined;
 }
+// OpenAPI 3.1 / JSON Schema 2020-12 allows `type` to be an array of type names
+// (e.g. `["string", "null"]`). Normalize to a single name and a pretty-printed
+// union form joined with ` | `.
+function normalizeType(type) {
+    if (Array.isArray(type)) {
+        const filtered = type.filter((t) => typeof t === "string");
+        if (filtered.length === 0)
+            return { isUnion: false };
+        if (filtered.length === 1)
+            return { single: filtered[0], isUnion: false };
+        return { pretty: filtered.join(" | "), isUnion: true };
+    }
+    if (typeof type === "string")
+        return { single: type, isUnion: false };
+    return { isUnion: false };
+}
 function prettyName(schema, circular) {
     // Handle enum-only schemas (valid in JSON Schema)
     // When enum is present without explicit type, treat as string
     if (schema.enum && !schema.type) {
         return "string";
     }
+    const t = normalizeType(schema.type);
     if (schema.format) {
+        if (t.single) {
+            return `${t.single}<${schema.format}>`;
+        }
+        if (t.isUnion) {
+            return `(${t.pretty})<${schema.format}>`;
+        }
         return schema.format;
     }
     if (schema.allOf) {
@@ -72,22 +95,23 @@ function prettyName(schema, circular) {
     if (schema.anyOf) {
         return "object";
     }
-    if (schema.type === "object") {
-        return schema.xml?.name ?? schema.type;
-        // return schema.type;
+    if (t.single === "object") {
+        return schema.xml?.name ?? t.single;
     }
-    if (schema.type === "array") {
-        return schema.xml?.name ?? schema.type;
-        // return schema.type;
+    if (t.single === "array") {
+        return schema.xml?.name ?? t.single;
     }
-    if (Array.isArray(schema.type)) {
-        return schema.type.join(" | ");
+    if (t.isUnion) {
+        return t.pretty;
     }
-    return schema.title ?? schema.type;
+    return schema.title ?? t.single;
 }
 function getSchemaName(schema, circular) {
     if (schema.items) {
-        return getSchemaName(schema.items, circular) + "[]";
+        const items = schema.items;
+        const inner = getSchemaName(items, circular);
+        const needsParens = Array.isArray(items.type) && items.type.length > 1;
+        return needsParens ? `(${inner})[]` : `${inner}[]`;
     }
     return prettyName(schema, circular) ?? "";
 }

package/lib/markdown/schema.test.js

@@ -48,4 +48,39 @@ describe("getSchemaName", () => {
         };
         expect((0, schema_1.getSchemaName)(schema)).toBe("integer[][][]");
     });
+    it("joins OpenAPI 3.1 type arrays with ` | ` (issue #950)", () => {
+        const schema = { type: ["string", "null"] };
+        expect((0, schema_1.getSchemaName)(schema)).toBe("string | null");
+    });
+    it("unwraps a single-element type array", () => {
+        const schema = { type: ["integer"] };
+        expect((0, schema_1.getSchemaName)(schema)).toBe("integer");
+    });
+    it("renders single type with format as `type<format>`", () => {
+        const schema = {
+            type: "string",
+            format: "uuid",
+        };
+        expect((0, schema_1.getSchemaName)(schema)).toBe("string<uuid>");
+    });
+    it("renders type union with format", () => {
+        const schema = {
+            type: ["string", "null"],
+            format: "uuid",
+        };
+        expect((0, schema_1.getSchemaName)(schema)).toBe("(string | null)<uuid>");
+    });
+    it("resolves type from an allOf wrapper that contains an enum", () => {
+        const schema = {
+            allOf: [{ type: "string", enum: ["a", "b"] }],
+        };
+        expect((0, schema_1.getSchemaName)(schema)).toBe("string");
+    });
+    it("renders array of items whose type is a union", () => {
+        const schema = {
+            type: "array",
+            items: { type: ["string", "null"] },
+        };
+        expect((0, schema_1.getSchemaName)(schema)).toBe("(string | null)[]");
+    });
 });

package/lib/theme/ApiItem/index.js

@@ -101,9 +101,21 @@ function ApiItem(props) {
     api?.parameters?.forEach((param) => {
       const paramType = param.in;
       const paramsArray = params[paramType];
-      const defaultValue = param.schema?.default;
+      const p = param;
+      // Prefill order: schema.default, then example sources. `default` is
+      // semantically a server-side fallback, so for required params authors
+      // typically rely on `example` / `examples`. See #544 and #1079.
+      const firstNamedExample =
+        p.examples && typeof p.examples === "object"
+          ? Object.values(p.examples)[0]?.value
+          : undefined;
+      const prefill =
+        p.schema?.default ??
+        p.example ??
+        p.schema?.example ??
+        firstNamedExample;
       const initialized =
-        defaultValue !== undefined ? { ...param, value: defaultValue } : param;
+        prefill !== undefined ? { ...param, value: prefill } : param;
       paramsArray?.push(initialized);
     });
     const auth = (0, slice_1.createAuth)({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "0.0.0-1268",
+  "version": "0.0.0-1294",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -38,7 +38,7 @@
     "@types/postman-collection": "^3.5.11",
     "@types/react-modal": "^3.16.3",
     "concurrently": "^9.2.0",
-    "docusaurus-plugin-openapi-docs": "0.0.0-1268",
+    "docusaurus-plugin-openapi-docs": "0.0.0-1294",
     "docusaurus-plugin-sass": "^0.2.6",
     "eslint-plugin-prettier": "^5.5.1"
   },
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "27848b60d7a6efd00d8a202a554b81152e24408e"
+  "gitHead": "dcce97d6a3cae4f76af8f02e81571e8ce5a394ac"
 }

package/src/markdown/schema.test.ts

@@ -58,4 +58,45 @@ describe("getSchemaName", () => {
     } as SchemaObject;
     expect(getSchemaName(schema)).toBe("integer[][][]");
   });
+
+  it("joins OpenAPI 3.1 type arrays with ` | ` (issue #950)", () => {
+    const schema = { type: ["string", "null"] } as unknown as SchemaObject;
+    expect(getSchemaName(schema)).toBe("string | null");
+  });
+
+  it("unwraps a single-element type array", () => {
+    const schema = { type: ["integer"] } as unknown as SchemaObject;
+    expect(getSchemaName(schema)).toBe("integer");
+  });
+
+  it("renders single type with format as `type<format>`", () => {
+    const schema = {
+      type: "string",
+      format: "uuid",
+    } as SchemaObject;
+    expect(getSchemaName(schema)).toBe("string<uuid>");
+  });
+
+  it("renders type union with format", () => {
+    const schema = {
+      type: ["string", "null"],
+      format: "uuid",
+    } as unknown as SchemaObject;
+    expect(getSchemaName(schema)).toBe("(string | null)<uuid>");
+  });
+
+  it("resolves type from an allOf wrapper that contains an enum", () => {
+    const schema = {
+      allOf: [{ type: "string", enum: ["a", "b"] }],
+    } as unknown as SchemaObject;
+    expect(getSchemaName(schema)).toBe("string");
+  });
+
+  it("renders array of items whose type is a union", () => {
+    const schema: SchemaObject = {
+      type: "array",
+      items: { type: ["string", "null"] } as any,
+    } as SchemaObject;
+    expect(getSchemaName(schema)).toBe("(string | null)[]");
+  });
 });

package/src/markdown/schema.ts

@@ -48,6 +48,24 @@ function getTypeFromSchema(schema: SchemaObject): string | undefined {
   return undefined;
 }
 
+// OpenAPI 3.1 / JSON Schema 2020-12 allows `type` to be an array of type names
+// (e.g. `["string", "null"]`). Normalize to a single name and a pretty-printed
+// union form joined with ` | `.
+function normalizeType(type: unknown): {
+  single?: string;
+  pretty?: string;
+  isUnion: boolean;
+} {
+  if (Array.isArray(type)) {
+    const filtered = type.filter((t): t is string => typeof t === "string");
+    if (filtered.length === 0) return { isUnion: false };
+    if (filtered.length === 1) return { single: filtered[0], isUnion: false };
+    return { pretty: filtered.join(" | "), isUnion: true };
+  }
+  if (typeof type === "string") return { single: type, isUnion: false };
+  return { isUnion: false };
+}
+
 function prettyName(schema: SchemaObject, circular?: boolean) {
   // Handle enum-only schemas (valid in JSON Schema)
   // When enum is present without explicit type, treat as string
@@ -55,7 +73,15 @@ function prettyName(schema: SchemaObject, circular?: boolean) {
     return "string";
   }
 
+  const t = normalizeType(schema.type);
+
   if (schema.format) {
+    if (t.single) {
+      return `${t.single}<${schema.format}>`;
+    }
+    if (t.isUnion) {
+      return `(${t.pretty})<${schema.format}>`;
+    }
     return schema.format;
   }
 
@@ -83,21 +109,19 @@ function prettyName(schema: SchemaObject, circular?: boolean) {
     return "object";
   }
 
-  if (schema.type === "object") {
-    return schema.xml?.name ?? schema.type;
-    // return schema.type;
+  if (t.single === "object") {
+    return schema.xml?.name ?? t.single;
   }
 
-  if (schema.type === "array") {
-    return schema.xml?.name ?? schema.type;
-    // return schema.type;
+  if (t.single === "array") {
+    return schema.xml?.name ?? t.single;
   }
 
-  if (Array.isArray(schema.type)) {
-    return schema.type.join(" | ");
+  if (t.isUnion) {
+    return t.pretty;
   }
 
-  return schema.title ?? schema.type;
+  return schema.title ?? t.single;
 }
 
 export function getSchemaName(
@@ -105,7 +129,11 @@ export function getSchemaName(
   circular?: boolean
 ): string {
   if (schema.items) {
-    return getSchemaName(schema.items as SchemaObject, circular) + "[]";
+    const items = schema.items as SchemaObject;
+    const inner = getSchemaName(items, circular);
+    const needsParens =
+      Array.isArray((items as any).type) && (items as any).type.length > 1;
+    return needsParens ? `(${inner})[]` : `${inner}[]`;
   }
 
   return prettyName(schema, circular) ?? "";

package/src/theme/ApiItem/index.tsx

@@ -123,10 +123,22 @@ export default function ApiItem(props: Props): JSX.Element {
       (param: { in: "path" | "query" | "header" | "cookie" }) => {
         const paramType = param.in;
         const paramsArray: ParameterObject[] = params[paramType];
-        const defaultValue = (param as any).schema?.default;
+        const p = param as any;
+        // Prefill order: schema.default, then example sources. `default` is
+        // semantically a server-side fallback, so for required params authors
+        // typically rely on `example` / `examples`. See #544 and #1079.
+        const firstNamedExample =
+          p.examples && typeof p.examples === "object"
+            ? (Object.values(p.examples)[0] as any)?.value
+            : undefined;
+        const prefill =
+          p.schema?.default ??
+          p.example ??
+          p.schema?.example ??
+          firstNamedExample;
         const initialized =
-          defaultValue !== undefined
-            ? ({ ...param, value: defaultValue } as unknown as ParameterObject)
+          prefill !== undefined
+            ? ({ ...param, value: prefill } as unknown as ParameterObject)
             : (param as ParameterObject);
         paramsArray?.push(initialized);
       }