docusaurus-plugin-openapi-docs 1.1.8 → 1.1.11

package/lib/openapi/createResponseExample.js

@@ -0,0 +1,169 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sampleResponseFromSchema = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const createResponseSchema_1 = require("../markdown/createResponseSchema");
+const 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, prop, obj) {
+    // 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] = (0, exports.sampleResponseFromSchema)(prop.oneOf[0]);
+    }
+    else if (prop.anyOf) {
+        obj[name] = (0, exports.sampleResponseFromSchema)(prop.anyOf[0]);
+    }
+    else if (prop.allOf) {
+        const { mergedSchemas } = (0, createResponseSchema_1.mergeAllOf)(prop.allOf);
+        sampleResponseFromProp(name, mergedSchemas, obj);
+    }
+    else {
+        obj[name] = (0, exports.sampleResponseFromSchema)(prop);
+    }
+    return obj;
+}
+const sampleResponseFromSchema = (schema = {}) => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        let { type, example, allOf, oneOf, anyOf, properties, items } = schema;
+        // TODO: determine if we should always ignore the example when creating from schema
+        // if (example !== undefined) {
+        //   return example;
+        // }
+        if (allOf) {
+            const { mergedSchemas } = (0, createResponseSchema_1.mergeAllOf)(allOf);
+            if (mergedSchemas.properties) {
+                for (const [key, value] of Object.entries(mergedSchemas.properties)) {
+                    if (value.writeOnly && value.writeOnly === true) {
+                        delete mergedSchemas.properties[key];
+                    }
+                }
+            }
+            return (0, exports.sampleResponseFromSchema)(mergedSchemas);
+        }
+        if (oneOf) {
+            // Just go with first schema
+            return (0, exports.sampleResponseFromSchema)(oneOf[0]);
+        }
+        if (anyOf) {
+            // Just go with first schema
+            return (0, exports.sampleResponseFromSchema)(anyOf[0]);
+        }
+        if (!type) {
+            if (properties) {
+                type = "object";
+            }
+            else if (items) {
+                type = "array";
+            }
+            else {
+                return;
+            }
+        }
+        if (type === "object") {
+            let obj = {};
+            for (let [name, prop] of Object.entries(properties !== null && properties !== void 0 ? properties : {})) {
+                if (prop.properties) {
+                    for (const [key, value] of Object.entries(prop.properties)) {
+                        if (value.writeOnly && value.writeOnly === true) {
+                            delete prop.properties[key];
+                        }
+                    }
+                }
+                if (prop.items && prop.items.properties) {
+                    for (const [key, value] of Object.entries(prop.items.properties)) {
+                        if (value.writeOnly && value.writeOnly === 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 === null || items === void 0 ? void 0 : items.anyOf)) {
+                return items === null || items === void 0 ? void 0 : items.anyOf.map((item) => (0, exports.sampleResponseFromSchema)(item));
+            }
+            if (Array.isArray(items === null || items === void 0 ? void 0 : items.oneOf)) {
+                return items === null || items === void 0 ? void 0 : items.oneOf.map((item) => (0, exports.sampleResponseFromSchema)(item));
+            }
+            return [(0, exports.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_1.default.yellow("WARNING: failed to create example from schema object:", err));
+        return;
+    }
+};
+exports.sampleResponseFromSchema = sampleResponseFromSchema;
+function primitive(schema = {}) {
+    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) {
+    if (Array.isArray(arr)) {
+        return arr;
+    }
+    return [arr];
+}

package/lib/openapi/openapi.js

@@ -19,7 +19,7 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const cloneDeep_1 = __importDefault(require("lodash/cloneDeep"));
 const kebabCase_1 = __importDefault(require("lodash/kebabCase"));
 const index_1 = require("../index");
-const createExample_1 = require("./createExample");
+const createRequestExample_1 = require("./createRequestExample");
 const loadAndResolveSpec_1 = require("./utils/loadAndResolveSpec");
 /**
  * Convenience function for converting raw JSON to a Postman Collection object.
@@ -134,7 +134,7 @@ function createItems(openapiData, sidebarOptions) {
             let jsonRequestBodyExample;
             const body = (_o = (_m = operationObject.requestBody) === null || _m === void 0 ? void 0 : _m.content) === null || _o === void 0 ? void 0 : _o["application/json"];
             if (body === null || body === void 0 ? void 0 : body.schema) {
-                jsonRequestBodyExample = (0, createExample_1.sampleFromSchema)(body.schema);
+                jsonRequestBodyExample = (0, createRequestExample_1.sampleRequestFromSchema)(body.schema);
             }
             // Handle vendor JSON media types
             const bodyContent = (_p = operationObject.requestBody) === null || _p === void 0 ? void 0 : _p.content;
@@ -143,7 +143,7 @@ function createItems(openapiData, sidebarOptions) {
                 if (firstBodyContentKey.endsWith("+json")) {
                     const firstBody = bodyContent[firstBodyContentKey];
                     if (firstBody === null || firstBody === void 0 ? void 0 : firstBody.schema) {
-                        jsonRequestBodyExample = (0, createExample_1.sampleFromSchema)(firstBody.schema);
+                        jsonRequestBodyExample = (0, createRequestExample_1.sampleRequestFromSchema)(firstBody.schema);
                     }
                 }
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.1.8",
+  "version": "1.1.11",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -59,7 +59,8 @@
     "slugify": "^1.6.5",
     "swagger2openapi": "^7.0.8",
     "url-template": "^3.0.0",
-    "webpack": "^5.61.0"
+    "webpack": "^5.61.0",
+    "xml-formatter": "^2.6.1"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0"
@@ -67,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "619aa16c52e6de8fd752ff583681b0da093b679c"
+  "gitHead": "329709c2d588d2a689a2f84d392b5cc11d6cdd02"
 }

package/src/index.ts

@@ -23,41 +23,51 @@ export function isURL(str: string): boolean {
   return /^(https?:)\/\//m.test(str);
 }
 
-export function getDocsData(
-  dataArray: any[],
-  filter: string
+export function getDocsPluginConfig(
+  presetsPlugins: any[],
+  pluginId: string
 ): Object | undefined {
   // eslint-disable-next-line array-callback-return
-  const filteredData = dataArray.filter((data) => {
-    if (data[0] === filter) {
+  const filteredConfig = presetsPlugins.filter((data) => {
+    if (data[0] === pluginId) {
       return data[1];
     }
 
     // Search plugin-content-docs instances
     if (data[0] === "@docusaurus/plugin-content-docs") {
-      const pluginId = data[1].id ? data[1].id : "default";
-      if (pluginId === filter) {
+      const configPluginId = data[1].id ? data[1].id : "default";
+      if (configPluginId === pluginId) {
         return data[1];
       }
     }
   })[0];
-  if (filteredData) {
+  if (filteredConfig) {
     // Search presets, e.g. "classic"
-    if (filteredData[0] === filter) {
-      return filteredData[1].docs;
+    if (filteredConfig[0] === pluginId) {
+      return filteredConfig[1].docs;
     }
 
     // Search plugin-content-docs instances
-    if (filteredData[0] === "@docusaurus/plugin-content-docs") {
-      const pluginId = filteredData[1].id ? filteredData[1].id : "default";
-      if (pluginId === filter) {
-        return filteredData[1];
+    if (filteredConfig[0] === "@docusaurus/plugin-content-docs") {
+      const configPluginId = filteredConfig[1].id
+        ? filteredConfig[1].id
+        : "default";
+      if (configPluginId === pluginId) {
+        return filteredConfig[1];
       }
     }
   }
   return;
 }
 
+function getPluginConfig(plugins: any[], pluginId: string): any {
+  return plugins.filter((data) => data[1].id === pluginId)[0][1];
+}
+
+function getPluginInstances(plugins: any[]): any {
+  return plugins.filter((data) => data[0] === "docusaurus-plugin-openapi-docs");
+}
+
 export default function pluginOpenAPIDocs(
   context: LoadContext,
   options: PluginOptions
@@ -69,7 +79,7 @@ export default function pluginOpenAPIDocs(
   const presets: any = siteConfig.presets;
   const plugins: any = siteConfig.plugins;
   const presetsPlugins = presets.concat(plugins);
-  const docData: any = getDocsData(presetsPlugins, docsPluginId);
+  const docData: any = getDocsPluginConfig(presetsPlugins, docsPluginId);
   const docRouteBasePath = docData ? docData.routeBasePath : undefined;
   const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
@@ -108,9 +118,7 @@ export default function pluginOpenAPIDocs(
           docPath
         );
 
-        const sidebarSliceTemplate = template
-          ? fs.readFileSync(template).toString()
-          : `module.exports = {{{slice}}};`;
+        const sidebarSliceTemplate = `module.exports = {{{slice}}};`;
 
         const view = render(sidebarSliceTemplate, {
           slice: JSON.stringify(sidebarSlice),
@@ -162,12 +170,11 @@ info_path: {{{infoPath}}}
 {{{markdown}}}
       `;
 
-      const infoMdTemplate = template
-        ? fs.readFileSync(template).toString()
-        : `---
+      const infoMdTemplate = `---
 id: {{{id}}}
 sidebar_label: {{{title}}}
 hide_title: true
+custom_edit_url: null
 ---
 
 {{{markdown}}}
@@ -180,12 +187,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 \`\`\`
       `;
 
-      const tagMdTemplate = template
-        ? fs.readFileSync(template).toString()
-        : `---
+      const tagMdTemplate = `---
 id: {{{id}}}
 title: {{{description}}}
 description: {{{description}}}
+custom_edit_url: null
 ---
 
 {{{markdown}}}
@@ -392,25 +398,52 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         )
         .usage("<id>")
         .arguments("<id>")
-        .action(async (id) => {
+        .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+        .action(async (id, instance) => {
+          const options = instance.opts();
+          const pluginId = options.pluginId;
+          const pluginInstances = getPluginInstances(plugins);
+          let targetConfig: any;
+          if (pluginId) {
+            try {
+              const pluginConfig = getPluginConfig(plugins, pluginId);
+              targetConfig = pluginConfig.config ?? {};
+            } catch {
+              console.error(
+                chalk.red(`OpenAPI docs plugin ID '${pluginId}' not found.`)
+              );
+              return;
+            }
+          } else {
+            if (pluginInstances.length > 1) {
+              console.error(
+                chalk.red(
+                  "OpenAPI docs plugin ID must be specified when more than one plugin instance exists."
+                )
+              );
+              return;
+            }
+            targetConfig = config;
+          }
+
           if (id === "all") {
-            if (config[id]) {
+            if (targetConfig[id]) {
               console.error(
                 chalk.red(
                   "Can't use id 'all' for OpenAPI docs configuration key."
                 )
               );
             } else {
-              Object.keys(config).forEach(async function (key) {
-                await generateApiDocs(config[key]);
+              Object.keys(targetConfig).forEach(async function (key) {
+                await generateApiDocs(targetConfig[key]);
               });
             }
-          } else if (!config[id]) {
+          } else if (!targetConfig[id]) {
             console.error(
               chalk.red(`ID '${id}' does not exist in OpenAPI docs config.`)
             );
           } else {
-            await generateApiDocs(config[id]);
+            await generateApiDocs(targetConfig[id]);
           }
         });
 
@@ -421,9 +454,35 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         )
         .usage("<id:version>")
         .arguments("<id:version>")
-        .action(async (id) => {
+        .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+        .action(async (id, instance) => {
+          const options = instance.opts();
+          const pluginId = options.pluginId;
+          const pluginInstances = getPluginInstances(plugins);
+          let targetConfig: any;
+          if (pluginId) {
+            try {
+              const pluginConfig = getPluginConfig(plugins, pluginId);
+              targetConfig = pluginConfig.config ?? {};
+            } catch {
+              console.error(
+                chalk.red(`OpenAPI docs plugin ID '${pluginId}' not found.`)
+              );
+              return;
+            }
+          } else {
+            if (pluginInstances.length > 1) {
+              console.error(
+                chalk.red(
+                  "OpenAPI docs plugin ID must be specified when more than one plugin instance exists."
+                )
+              );
+              return;
+            }
+            targetConfig = config;
+          }
           const [parentId, versionId] = id.split(":");
-          const parentConfig = Object.assign({}, config[parentId]);
+          const parentConfig = Object.assign({}, targetConfig[parentId]);
 
           const version = parentConfig.version as string;
           const label = parentConfig.label as string;
@@ -432,7 +491,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
           let parentVersion = {} as any;
           parentVersion[version] = { label: label, baseUrl: baseUrl };
 
-          const { versions } = config[parentId] as any;
+          const { versions } = targetConfig[parentId] as any;
           const mergedVersions = Object.assign(parentVersion, versions);
 
           // Prepare for merge
@@ -484,21 +543,47 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         )
         .usage("<id>")
         .arguments("<id>")
-        .action(async (id) => {
+        .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+        .action(async (id, instance) => {
+          const options = instance.opts();
+          const pluginId = options.pluginId;
+          const pluginInstances = getPluginInstances(plugins);
+          let targetConfig: any;
+          if (pluginId) {
+            try {
+              const pluginConfig = getPluginConfig(plugins, pluginId);
+              targetConfig = pluginConfig.config ?? {};
+            } catch {
+              console.error(
+                chalk.red(`OpenAPI docs plugin ID '${pluginId}' not found.`)
+              );
+              return;
+            }
+          } else {
+            if (pluginInstances.length > 1) {
+              console.error(
+                chalk.red(
+                  "OpenAPI docs plugin ID must be specified when more than one plugin instance exists."
+                )
+              );
+              return;
+            }
+            targetConfig = config;
+          }
           if (id === "all") {
-            if (config[id]) {
+            if (targetConfig[id]) {
               console.error(
                 chalk.red(
                   "Can't use id 'all' for OpenAPI docs configuration key."
                 )
               );
             } else {
-              Object.keys(config).forEach(async function (key) {
-                await cleanApiDocs(config[key]);
+              Object.keys(targetConfig).forEach(async function (key) {
+                await cleanApiDocs(targetConfig[key]);
               });
             }
           } else {
-            await cleanApiDocs(config[id]);
+            await cleanApiDocs(targetConfig[id]);
           }
         });
 
@@ -509,11 +594,37 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         )
         .usage("<id:version>")
         .arguments("<id:version>")
-        .action(async (id) => {
+        .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+        .action(async (id, instance) => {
+          const options = instance.opts();
+          const pluginId = options.pluginId;
+          const pluginInstances = getPluginInstances(plugins);
+          let targetConfig: any;
+          if (pluginId) {
+            try {
+              const pluginConfig = getPluginConfig(plugins, pluginId);
+              targetConfig = pluginConfig.config ?? {};
+            } catch {
+              console.error(
+                chalk.red(`OpenAPI docs plugin ID '${pluginId}' not found.`)
+              );
+              return;
+            }
+          } else {
+            if (pluginInstances.length > 1) {
+              console.error(
+                chalk.red(
+                  "OpenAPI docs plugin ID must be specified when more than one plugin instance exists."
+                )
+              );
+              return;
+            }
+            targetConfig = config;
+          }
           const [parentId, versionId] = id.split(":");
-          const { versions } = config[parentId] as any;
+          const { versions } = targetConfig[parentId] as any;
 
-          const parentConfig = Object.assign({}, config[parentId]);
+          const parentConfig = Object.assign({}, targetConfig[parentId]);
           delete parentConfig.versions;
 
           if (versionId === "all") {