docusaurus-plugin-openapi-docs 1.1.8 → 1.1.9

package/src/markdown/createStatusCodes.ts

@@ -5,6 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import format from "xml-formatter";
+
+import { sampleResponseFromSchema } from "../openapi/createResponseExample";
 import { ApiItem } from "../types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
@@ -13,6 +16,43 @@ import { createResponseSchema } from "./createResponseSchema";
 import { create } from "./utils";
 import { guard } from "./utils";
 
+export default function json2xml(o: any, tab: any) {
+  var toXml = function (v: any, name: string, ind: any) {
+      var xml = "";
+      if (v instanceof Array) {
+        for (var i = 0, n = v.length; i < n; i++)
+          xml += ind + toXml(v[i], name, ind + "\t") + "\n";
+      } else if (typeof v == "object") {
+        var hasChild = false;
+        xml += ind + "<" + name;
+        for (var m in v) {
+          if (m.charAt(0) === "@")
+            xml += " " + m.substr(1) + '="' + v[m].toString() + '"';
+          else hasChild = true;
+        }
+        xml += hasChild ? ">" : "/>";
+        if (hasChild) {
+          for (var m2 in v) {
+            if (m2 === "#text") xml += v[m2];
+            else if (m2 === "#cdata") xml += "<![CDATA[" + v[m2] + "]]>";
+            else if (m2.charAt(0) !== "@") xml += toXml(v[m2], m2, ind + "\t");
+          }
+          xml +=
+            (xml.charAt(xml.length - 1) === "\n" ? ind : "") +
+            "</" +
+            name +
+            ">";
+        }
+      } else {
+        xml += ind + "<" + name + ">" + v.toString() + "</" + name + ">";
+      }
+      return xml;
+    },
+    xml = "";
+  for (var m3 in o) xml += toXml(o[m3], m3, "");
+  return tab ? xml.replace(/\t/g, tab) : xml.replace(/\t|\n/g, "");
+}
+
 interface Props {
   responses: ApiItem["responses"];
 }
@@ -67,7 +107,17 @@ function createResponseHeaders(responseHeaders: any) {
   );
 }
 
-export function createResponseExamples(responseExamples: any) {
+export function createResponseExamples(
+  responseExamples: any,
+  mimeType: string
+) {
+  let language = "shell";
+  if (mimeType.endsWith("json")) {
+    language = "json";
+  }
+  if (mimeType.endsWith("xml")) {
+    language = "xml";
+  }
   return Object.entries(responseExamples).map(
     ([exampleName, exampleValue]: any) => {
       const camelToSpaceName = exampleName.replace(/([A-Z])/g, " $1");
@@ -81,6 +131,7 @@ export function createResponseExamples(responseExamples: any) {
           children: [
             create("ResponseSamples", {
               responseExample: JSON.stringify(exampleValue.value, null, 2),
+              language: language,
             }),
           ],
         });
@@ -91,6 +142,7 @@ export function createResponseExamples(responseExamples: any) {
         children: [
           create("ResponseSamples", {
             responseExample: exampleValue.value,
+            language: language,
           }),
         ],
       });
@@ -98,7 +150,14 @@ export function createResponseExamples(responseExamples: any) {
   );
 }
 
-export function createResponseExample(responseExample: any) {
+export function createResponseExample(responseExample: any, mimeType: string) {
+  let language = "shell";
+  if (mimeType.endsWith("json")) {
+    language = "json";
+  }
+  if (mimeType.endsWith("xml")) {
+    language = "xml";
+  }
   if (typeof responseExample === "object") {
     return create("TabItem", {
       label: `Example`,
@@ -106,6 +165,7 @@ export function createResponseExample(responseExample: any) {
       children: [
         create("ResponseSamples", {
           responseExample: JSON.stringify(responseExample, null, 2),
+          language: language,
         }),
       ],
     });
@@ -116,11 +176,69 @@ export function createResponseExample(responseExample: any) {
     children: [
       create("ResponseSamples", {
         responseExample: responseExample,
+        language: language,
       }),
     ],
   });
 }
 
+export function createExampleFromSchema(schema: any, mimeType: string) {
+  const responseExample = sampleResponseFromSchema(schema);
+  if (mimeType.endsWith("xml")) {
+    let responseExampleObject;
+    try {
+      responseExampleObject = JSON.parse(JSON.stringify(responseExample));
+    } catch {
+      return undefined;
+    }
+
+    if (typeof responseExampleObject === "object") {
+      let xmlExample;
+      try {
+        xmlExample = format(json2xml(responseExampleObject, ""), {
+          indentation: "  ",
+          lineSeparator: "\n",
+          collapseContent: true,
+        });
+      } catch {
+        const xmlExampleWithRoot = { root: responseExampleObject };
+        try {
+          xmlExample = format(json2xml(xmlExampleWithRoot, ""), {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          });
+        } catch {
+          xmlExample = json2xml(responseExampleObject, "");
+        }
+      }
+      return create("TabItem", {
+        label: `Example (from schema)`,
+        value: `Example (from schema)`,
+        children: [
+          create("ResponseSamples", {
+            responseExample: xmlExample,
+            language: "xml",
+          }),
+        ],
+      });
+    }
+  }
+  if (typeof responseExample === "object") {
+    return create("TabItem", {
+      label: `Example (from schema)`,
+      value: `Example (from schema)`,
+      children: [
+        create("ResponseSamples", {
+          responseExample: JSON.stringify(responseExample, null, 2),
+          language: "json",
+        }),
+      ],
+    });
+  }
+  return undefined;
+}
+
 export function createStatusCodes({ responses }: Props) {
   if (responses === undefined) {
     return undefined;
@@ -147,8 +265,8 @@ export function createStatusCodes({ responses }: Props) {
               }),
               responseHeaders &&
                 createDetails({
-                  "data-collaposed": false,
-                  open: true,
+                  "data-collaposed": true,
+                  open: false,
                   style: { textAlign: "left", marginBottom: "1rem" },
                   children: [
                     createDetailsSummary({

package/src/openapi/{createExample.ts → createRequestExample.ts}

@@ -51,14 +51,48 @@ const primitives: Primitives = {
   array: {},
 };
 
-export const sampleFromSchema = (schema: SchemaObject = {}): any => {
+function sampleRequestFromProp(name: string, prop: any, obj: any): any {
+  // Handle resolved circular props
+  if (typeof prop === "object" && Object.keys(prop).length === 0) {
+    obj[name] = prop;
+    return obj;
+  }
+
+  // TODO: handle discriminators
+
+  if (prop.oneOf) {
+    obj[name] = sampleRequestFromSchema(prop.oneOf[0]);
+  } else if (prop.anyOf) {
+    obj[name] = sampleRequestFromSchema(prop.anyOf[0]);
+  } else if (prop.allOf) {
+    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
+      prop.allOf
+    );
+    sampleRequestFromProp(name, mergedSchemas, obj);
+  } else {
+    obj[name] = sampleRequestFromSchema(prop);
+  }
+  return obj;
+}
+
+export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
   try {
-    let { type, example, allOf, properties, items } = schema;
+    let { type, example, allOf, properties, items, oneOf, anyOf } = schema;
 
     if (example !== undefined) {
       return example;
     }
 
+    if (oneOf) {
+      // Just go with first schema
+      return sampleRequestFromSchema(oneOf[0]);
+    }
+
+    if (anyOf) {
+      // Just go with first schema
+      return sampleRequestFromSchema(anyOf[0]);
+    }
+
     if (allOf) {
       const { mergedSchemas }: { mergedSchemas: SchemaObject } =
         mergeAllOf(allOf);
@@ -69,7 +103,7 @@ export const sampleFromSchema = (schema: SchemaObject = {}): any => {
           }
         }
       }
-      return sampleFromSchema(mergedSchemas);
+      return sampleRequestFromSchema(mergedSchemas);
     }
 
     if (!type) {
@@ -104,21 +138,23 @@ export const sampleFromSchema = (schema: SchemaObject = {}): any => {
         if (prop.deprecated) {
           continue;
         }
-        obj[name] = sampleFromSchema(prop);
+
+        // Resolve schema from prop recursively
+        obj = sampleRequestFromProp(name, prop, obj);
       }
       return obj;
     }
 
     if (type === "array") {
       if (Array.isArray(items?.anyOf)) {
-        return items?.anyOf.map((item) => sampleFromSchema(item));
+        return items?.anyOf.map((item) => sampleRequestFromSchema(item));
       }
 
       if (Array.isArray(items?.oneOf)) {
-        return items?.oneOf.map((item) => sampleFromSchema(item));
+        return items?.oneOf.map((item) => sampleRequestFromSchema(item));
       }
 
-      return [sampleFromSchema(items)];
+      return [sampleRequestFromSchema(items)];
     }
 
     if (schema.enum) {

package/src/openapi/createResponseExample.ts

@@ -0,0 +1,205 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import chalk from "chalk";
+
+import { mergeAllOf } from "../markdown/createResponseSchema";
+import { SchemaObject } from "./types";
+
+interface OASTypeToTypeMap {
+  string: string;
+  number: number;
+  integer: number;
+  boolean: boolean;
+  object: any;
+  array: any[];
+}
+
+type Primitives = {
+  [OASType in keyof OASTypeToTypeMap]: {
+    [format: string]: (schema: SchemaObject) => OASTypeToTypeMap[OASType];
+  };
+};
+
+const primitives: Primitives = {
+  string: {
+    default: () => "string",
+    email: () => "user@example.com",
+    date: () => new Date().toISOString().substring(0, 10),
+    "date-time": () => new Date().toISOString().substring(0, 10),
+    uuid: () => "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    hostname: () => "example.com",
+    ipv4: () => "198.51.100.42",
+    ipv6: () => "2001:0db8:5b96:0000:0000:426f:8e17:642a",
+  },
+  number: {
+    default: () => 0,
+    float: () => 0.0,
+  },
+  integer: {
+    default: () => 0,
+  },
+  boolean: {
+    default: (schema) =>
+      typeof schema.default === "boolean" ? schema.default : true,
+  },
+  object: {},
+  array: {},
+};
+
+function sampleResponseFromProp(name: string, prop: any, obj: any): any {
+  // Handle resolved circular props
+  if (typeof prop === "object" && Object.keys(prop).length === 0) {
+    obj[name] = prop;
+    return obj;
+  }
+
+  // TODO: handle discriminators
+
+  if (prop.oneOf) {
+    obj[name] = sampleResponseFromSchema(prop.oneOf[0]);
+  } else if (prop.anyOf) {
+    obj[name] = sampleResponseFromSchema(prop.anyOf[0]);
+  } else if (prop.allOf) {
+    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
+      prop.allOf
+    );
+    sampleResponseFromProp(name, mergedSchemas, obj);
+  } else {
+    obj[name] = sampleResponseFromSchema(prop);
+  }
+  return obj;
+}
+
+export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
+  try {
+    let { type, example, allOf, oneOf, anyOf, properties, items } = schema;
+
+    if (example !== undefined) {
+      return example;
+    }
+
+    if (allOf) {
+      const { mergedSchemas }: { mergedSchemas: SchemaObject } =
+        mergeAllOf(allOf);
+      if (mergedSchemas.properties) {
+        for (const [key, value] of Object.entries(mergedSchemas.properties)) {
+          if (value.readOnly && value.readOnly === true) {
+            delete mergedSchemas.properties[key];
+          }
+        }
+      }
+      return sampleResponseFromSchema(mergedSchemas);
+    }
+
+    if (oneOf) {
+      // Just go with first schema
+      return sampleResponseFromSchema(oneOf[0]);
+    }
+
+    if (anyOf) {
+      // Just go with first schema
+      return sampleResponseFromSchema(anyOf[0]);
+    }
+
+    if (!type) {
+      if (properties) {
+        type = "object";
+      } else if (items) {
+        type = "array";
+      } else {
+        return;
+      }
+    }
+
+    if (type === "object") {
+      let obj: any = {};
+      for (let [name, prop] of Object.entries(properties ?? {})) {
+        if (prop.properties) {
+          for (const [key, value] of Object.entries(prop.properties)) {
+            if (value.readOnly && value.readOnly === true) {
+              delete prop.properties[key];
+            }
+          }
+        }
+
+        if (prop.items && prop.items.properties) {
+          for (const [key, value] of Object.entries(prop.items.properties)) {
+            if (value.readOnly && value.readOnly === true) {
+              delete prop.items.properties[key];
+            }
+          }
+        }
+
+        if (prop.deprecated) {
+          continue;
+        }
+
+        // Resolve schema from prop recursively
+        obj = sampleResponseFromProp(name, prop, obj);
+      }
+      return obj;
+    }
+
+    if (type === "array") {
+      if (Array.isArray(items?.anyOf)) {
+        return items?.anyOf.map((item) => sampleResponseFromSchema(item));
+      }
+
+      if (Array.isArray(items?.oneOf)) {
+        return items?.oneOf.map((item) => sampleResponseFromSchema(item));
+      }
+
+      return [sampleResponseFromSchema(items)];
+    }
+
+    if (schema.enum) {
+      if (schema.default) {
+        return schema.default;
+      }
+      return normalizeArray(schema.enum)[0];
+    }
+
+    if (schema.writeOnly && schema.writeOnly === true) {
+      return undefined;
+    }
+
+    return primitive(schema);
+  } catch (err) {
+    console.error(
+      chalk.yellow("WARNING: failed to create example from schema object:", err)
+    );
+    return;
+  }
+};
+
+function primitive(schema: SchemaObject = {}) {
+  let { type, format } = schema;
+
+  if (type === undefined) {
+    return;
+  }
+
+  let fn = schema.default ? () => schema.default : primitives[type].default;
+
+  if (format !== undefined) {
+    fn = primitives[type][format] || fn;
+  }
+
+  if (fn) {
+    return fn(schema);
+  }
+
+  return "Unknown Type: " + schema.type;
+}
+
+function normalizeArray(arr: any) {
+  if (Array.isArray(arr)) {
+    return arr;
+  }
+  return [arr];
+}

package/src/openapi/openapi.ts

@@ -25,7 +25,7 @@ import {
   SidebarOptions,
   TagPageMetadata,
 } from "../types";
-import { sampleFromSchema } from "./createExample";
+import { sampleRequestFromSchema } from "./createRequestExample";
 import { OpenApiObject, TagObject } from "./types";
 import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 
@@ -170,7 +170,7 @@ function createItems(
       let jsonRequestBodyExample;
       const body = operationObject.requestBody?.content?.["application/json"];
       if (body?.schema) {
-        jsonRequestBodyExample = sampleFromSchema(body.schema);
+        jsonRequestBodyExample = sampleRequestFromSchema(body.schema);
       }
 
       // Handle vendor JSON media types
@@ -180,7 +180,7 @@ function createItems(
         if (firstBodyContentKey.endsWith("+json")) {
           const firstBody = bodyContent[firstBodyContentKey];
           if (firstBody?.schema) {
-            jsonRequestBodyExample = sampleFromSchema(firstBody.schema);
+            jsonRequestBodyExample = sampleRequestFromSchema(firstBody.schema);
           }
         }
       }

package/lib/openapi/createExample.d.ts

@@ -1,2 +0,0 @@
-import { SchemaObject } from "./types";
-export declare const sampleFromSchema: (schema?: SchemaObject) => any;