docusaurus-plugin-openapi-docs 1.1.11 → 1.2.0

package/lib/index.js

@@ -68,11 +68,17 @@ function pluginOpenAPIDocs(context, options) {
     const presets = siteConfig.presets;
     const plugins = siteConfig.plugins;
     const presetsPlugins = presets.concat(plugins);
-    const docData = getDocsPluginConfig(presetsPlugins, docsPluginId);
-    const docRouteBasePath = docData ? docData.routeBasePath : undefined;
-    const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
-    async function generateApiDocs(options) {
+    let docData = getDocsPluginConfig(presetsPlugins, docsPluginId);
+    let docRouteBasePath = docData ? docData.routeBasePath : undefined;
+    let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
+    async function generateApiDocs(options, pluginId) {
         let { specPath, outputDir, template, sidebarOptions } = options;
+        // Override docPath if pluginId provided
+        if (pluginId) {
+            docData = getDocsPluginConfig(presetsPlugins, pluginId);
+            docRouteBasePath = docData ? docData.routeBasePath : undefined;
+            docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
+        }
         const contentPath = isURL(specPath)
             ? specPath
             : path_1.default.resolve(siteDir, specPath);
@@ -109,6 +115,8 @@ function pluginOpenAPIDocs(context, options) {
                 ? fs_1.default.readFileSync(template).toString()
                 : `---
 id: {{{id}}}
+title: "{{{title}}}"
+description: "{{{description}}}"
 {{^api}}
 sidebar_label: Introduction
 {{/api}}
@@ -137,6 +145,8 @@ info_path: {{{infoPath}}}
       `;
             const infoMdTemplate = `---
 id: {{{id}}}
+title: "{{{title}}}"
+description: "{{{description}}}"
 sidebar_label: {{{title}}}
 hide_title: true
 custom_edit_url: null
@@ -153,8 +163,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
       `;
             const tagMdTemplate = `---
 id: {{{id}}}
-title: {{{description}}}
-description: {{{description}}}
+title: "{{{description}}}"
+description: "{{{description}}}"
 custom_edit_url: null
 ---
 
@@ -192,6 +202,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 if (item.type === "api") {
                     if (!fs_1.default.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
                         try {
+                            // kebabCase(arg) returns 0-length string when arg is undefined
+                            if (item.id.length === 0) {
+                                throw Error("Operation must have summary or operationId defined");
+                            }
                             fs_1.default.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
                             console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.api.mdx"`));
                         }
@@ -307,10 +321,12 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 const pluginId = options.pluginId;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
+                let targetDocsPluginId;
                 if (pluginId) {
                     try {
                         const pluginConfig = getPluginConfig(plugins, pluginId);
                         targetConfig = (_a = pluginConfig.config) !== null && _a !== void 0 ? _a : {};
+                        targetDocsPluginId = pluginConfig.docsPluginId;
                     }
                     catch {
                         console.error(chalk_1.default.red(`OpenAPI docs plugin ID '${pluginId}' not found.`));
@@ -330,7 +346,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                     }
                     else {
                         Object.keys(targetConfig).forEach(async function (key) {
-                            await generateApiDocs(targetConfig[key]);
+                            await generateApiDocs(targetConfig[key], targetDocsPluginId);
                         });
                     }
                 }
@@ -338,7 +354,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                     console.error(chalk_1.default.red(`ID '${id}' does not exist in OpenAPI docs config.`));
                 }
                 else {
-                    await generateApiDocs(targetConfig[id]);
+                    await generateApiDocs(targetConfig[id], targetDocsPluginId);
                 }
             });
             cli
@@ -353,10 +369,12 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 const pluginId = options.pluginId;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
+                let targetDocsPluginId;
                 if (pluginId) {
                     try {
                         const pluginConfig = getPluginConfig(plugins, pluginId);
                         targetConfig = (_a = pluginConfig.config) !== null && _a !== void 0 ? _a : {};
+                        targetDocsPluginId = pluginConfig.docsPluginId;
                     }
                     catch {
                         console.error(chalk_1.default.red(`OpenAPI docs plugin ID '${pluginId}' not found.`));
@@ -397,7 +415,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                                 ...parentConfig,
                                 ...versionConfig,
                             };
-                            await generateApiDocs(mergedConfig);
+                            await generateApiDocs(mergedConfig, targetDocsPluginId);
                         });
                     }
                 }
@@ -411,7 +429,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                         ...versionConfig,
                     };
                     await generateVersions(mergedVersions, parentConfig.outputDir);
-                    await generateApiDocs(mergedConfig);
+                    await generateApiDocs(mergedConfig, targetDocsPluginId);
                 }
             });
             cli

package/lib/markdown/createRequestSchema.js

@@ -43,7 +43,7 @@ exports.mergeAllOf = mergeAllOf;
  */
 function createAnyOneOf(schema) {
     const type = schema.oneOf ? "oneOf" : "anyOf";
-    return (0, utils_1.create)("li", {
+    return (0, utils_1.create)("div", {
         children: [
             (0, utils_1.create)("div", {
                 children: [

package/lib/markdown/createResponseSchema.js

@@ -44,7 +44,7 @@ exports.mergeAllOf = mergeAllOf;
  */
 function createAnyOneOf(schema) {
     const type = schema.oneOf ? "oneOf" : "anyOf";
-    return (0, utils_1.create)("li", {
+    return (0, utils_1.create)("div", {
         children: [
             (0, utils_1.create)("div", {
                 children: [

package/lib/markdown/createStatusCodes.js

@@ -68,7 +68,7 @@ function createResponseHeaders(responseHeaders) {
             Object.entries(responseHeaders).map(([headerName, headerObj]) => {
                 const { description, schema: { type }, example, } = headerObj;
                 return (0, utils_1.create)("li", {
-                    class: "schemaItem",
+                    className: "schemaItem",
                     children: [
                         (0, createDetailsSummary_1.createDetailsSummary)({
                             children: [

package/lib/openapi/openapi.js

@@ -95,7 +95,9 @@ function createItems(openapiData, sidebarOptions) {
             id: infoId,
             unversionedId: infoId,
             title: openapiData.info.title,
-            description: openapiData.info.description,
+            description: openapiData.info.description
+                ? openapiData.info.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                : "",
             frontMatter: {},
             securitySchemes: (_b = openapiData.components) === null || _b === void 0 ? void 0 : _b.securitySchemes,
             info: {
@@ -155,7 +157,9 @@ function createItems(openapiData, sidebarOptions) {
                 infoId: infoId !== null && infoId !== void 0 ? infoId : "",
                 unversionedId: baseId,
                 title: title,
-                description: description !== null && description !== void 0 ? description : "",
+                description: operationObject.description
+                    ? operationObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                    : "",
                 frontMatter: {},
                 api: {
                     ...defaults,

package/lib/openapi/utils/loadAndResolveSpec.js

@@ -28,12 +28,15 @@ function serializer(replacer, cycleReplacer) {
         // Resolve discriminator ref pointers
         if ((value === null || value === void 0 ? void 0 : value.discriminator) !== undefined) {
             const parser = new OpenAPIParser_1.OpenAPIParser(stack[0]);
-            for (let [k, v] of Object.entries(value.discriminator.mapping)) {
-                const discriminator = k;
-                if (typeof v === "string" && v.charAt(0) === "#") {
-                    const ref = v;
-                    const resolvedRef = parser.byRef(ref);
-                    value.discriminator.mapping[discriminator] = resolvedRef;
+            if (value.discriminator.mapping &&
+                typeof value.discriminator.mapping === "object") {
+                for (let [k, v] of Object.entries(value.discriminator.mapping)) {
+                    const discriminator = k;
+                    if (typeof v === "string" && v.charAt(0) === "#") {
+                        const ref = v;
+                        const resolvedRef = parser.byRef(ref);
+                        value.discriminator.mapping[discriminator] = resolvedRef;
+                    }
                 }
             }
         }

package/lib/sidebars/index.js

@@ -36,13 +36,12 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
     const operationTags = (0, uniq_1.default)(apiItems
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
-    // Only include operation tags that are globally defined
-    const apiTags = [];
+    // Combine globally defined tags with operation tags
+    let apiTags = [];
     tags.flat().forEach((tag) => {
-        if (operationTags.includes(tag.name)) {
-            apiTags.push(tag.name);
-        }
+        apiTags.push(tag.name);
     });
+    apiTags = (0, uniq_1.default)(apiTags.concat(operationTags));
     const basePath = docPath
         ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
         : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -40,10 +40,10 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^9.0.9",
-    "@docusaurus/mdx-loader": "2.0.1",
-    "@docusaurus/plugin-content-docs": "2.0.1",
-    "@docusaurus/utils": "2.0.1",
-    "@docusaurus/utils-validation": "2.0.1",
+    "@docusaurus/mdx-loader": "^2.0.1",
+    "@docusaurus/plugin-content-docs": "^2.0.1",
+    "@docusaurus/utils": "^2.0.1",
+    "@docusaurus/utils-validation": "^2.0.1",
     "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
     "@paloaltonetworks/postman-collection": "^4.1.0",
     "@redocly/openapi-core": "^1.0.0-beta.103",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "329709c2d588d2a689a2f84d392b5cc11d6cdd02"
+  "gitHead": "fdbc413e36c3b7c202cc31606124c0a8eb76811b"
 }

package/src/index.ts

@@ -79,13 +79,20 @@ export default function pluginOpenAPIDocs(
   const presets: any = siteConfig.presets;
   const plugins: any = siteConfig.plugins;
   const presetsPlugins = presets.concat(plugins);
-  const docData: any = getDocsPluginConfig(presetsPlugins, docsPluginId);
-  const docRouteBasePath = docData ? docData.routeBasePath : undefined;
-  const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
+  let docData: any = getDocsPluginConfig(presetsPlugins, docsPluginId);
+  let docRouteBasePath = docData ? docData.routeBasePath : undefined;
+  let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
-  async function generateApiDocs(options: APIOptions) {
+  async function generateApiDocs(options: APIOptions, pluginId: any) {
     let { specPath, outputDir, template, sidebarOptions } = options;
 
+    // Override docPath if pluginId provided
+    if (pluginId) {
+      docData = getDocsPluginConfig(presetsPlugins, pluginId);
+      docRouteBasePath = docData ? docData.routeBasePath : undefined;
+      docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
+    }
+
     const contentPath = isURL(specPath)
       ? specPath
       : path.resolve(siteDir, specPath);
@@ -143,6 +150,8 @@ export default function pluginOpenAPIDocs(
         ? fs.readFileSync(template).toString()
         : `---
 id: {{{id}}}
+title: "{{{title}}}"
+description: "{{{description}}}"
 {{^api}}
 sidebar_label: Introduction
 {{/api}}
@@ -172,6 +181,8 @@ info_path: {{{infoPath}}}
 
       const infoMdTemplate = `---
 id: {{{id}}}
+title: "{{{title}}}"
+description: "{{{description}}}"
 sidebar_label: {{{title}}}
 hide_title: true
 custom_edit_url: null
@@ -189,8 +200,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
       const tagMdTemplate = `---
 id: {{{id}}}
-title: {{{description}}}
-description: {{{description}}}
+title: "{{{description}}}"
+description: "{{{description}}}"
 custom_edit_url: null
 ---
 
@@ -231,6 +242,12 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         if (item.type === "api") {
           if (!fs.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
             try {
+              // kebabCase(arg) returns 0-length string when arg is undefined
+              if (item.id.length === 0) {
+                throw Error(
+                  "Operation must have summary or operationId defined"
+                );
+              }
               fs.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
               console.log(
                 chalk.green(
@@ -404,10 +421,12 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
           const pluginId = options.pluginId;
           const pluginInstances = getPluginInstances(plugins);
           let targetConfig: any;
+          let targetDocsPluginId: any;
           if (pluginId) {
             try {
               const pluginConfig = getPluginConfig(plugins, pluginId);
               targetConfig = pluginConfig.config ?? {};
+              targetDocsPluginId = pluginConfig.docsPluginId;
             } catch {
               console.error(
                 chalk.red(`OpenAPI docs plugin ID '${pluginId}' not found.`)
@@ -435,7 +454,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
               );
             } else {
               Object.keys(targetConfig).forEach(async function (key) {
-                await generateApiDocs(targetConfig[key]);
+                await generateApiDocs(targetConfig[key], targetDocsPluginId);
               });
             }
           } else if (!targetConfig[id]) {
@@ -443,7 +462,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
               chalk.red(`ID '${id}' does not exist in OpenAPI docs config.`)
             );
           } else {
-            await generateApiDocs(targetConfig[id]);
+            await generateApiDocs(targetConfig[id], targetDocsPluginId);
           }
         });
 
@@ -460,10 +479,12 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
           const pluginId = options.pluginId;
           const pluginInstances = getPluginInstances(plugins);
           let targetConfig: any;
+          let targetDocsPluginId: any;
           if (pluginId) {
             try {
               const pluginConfig = getPluginConfig(plugins, pluginId);
               targetConfig = pluginConfig.config ?? {};
+              targetDocsPluginId = pluginConfig.docsPluginId;
             } catch {
               console.error(
                 chalk.red(`OpenAPI docs plugin ID '${pluginId}' not found.`)
@@ -516,7 +537,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                   ...parentConfig,
                   ...versionConfig,
                 };
-                await generateApiDocs(mergedConfig);
+                await generateApiDocs(mergedConfig, targetDocsPluginId);
               });
             }
           } else if (!versions[versionId]) {
@@ -532,7 +553,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
               ...versionConfig,
             };
             await generateVersions(mergedVersions, parentConfig.outputDir);
-            await generateApiDocs(mergedConfig);
+            await generateApiDocs(mergedConfig, targetDocsPluginId);
           }
         });
 

package/src/markdown/createRequestSchema.ts

@@ -46,7 +46,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
  */
 function createAnyOneOf(schema: SchemaObject): any {
   const type = schema.oneOf ? "oneOf" : "anyOf";
-  return create("li", {
+  return create("div", {
     children: [
       create("div", {
         children: [

package/src/markdown/createResponseSchema.ts

@@ -51,7 +51,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
  */
 function createAnyOneOf(schema: SchemaObject): any {
   const type = schema.oneOf ? "oneOf" : "anyOf";
-  return create("li", {
+  return create("div", {
     children: [
       create("div", {
         children: [

package/src/markdown/createStatusCodes.ts

@@ -70,7 +70,7 @@ function createResponseHeaders(responseHeaders: any) {
           }: any = headerObj;
 
           return create("li", {
-            class: "schemaItem",
+            className: "schemaItem",
             children: [
               createDetailsSummary({
                 children: [

package/src/openapi/openapi.ts

@@ -119,7 +119,12 @@ function createItems(
       id: infoId,
       unversionedId: infoId,
       title: openapiData.info.title,
-      description: openapiData.info.description,
+      description: openapiData.info.description
+        ? openapiData.info.description.replace(
+            /((?:^|[^\\])(?:\\{2})*)"/g,
+            "$1'"
+          )
+        : "",
       frontMatter: {},
       securitySchemes: openapiData.components?.securitySchemes,
       info: {
@@ -194,7 +199,12 @@ function createItems(
         infoId: infoId ?? "",
         unversionedId: baseId,
         title: title,
-        description: description ?? "",
+        description: operationObject.description
+          ? operationObject.description.replace(
+              /((?:^|[^\\])(?:\\{2})*)"/g,
+              "$1'"
+            )
+          : "",
         frontMatter: {},
         api: {
           ...defaults,

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -30,12 +30,17 @@ function serializer(replacer: any, cycleReplacer: any) {
     // Resolve discriminator ref pointers
     if (value?.discriminator !== undefined) {
       const parser = new OpenAPIParser(stack[0]);
-      for (let [k, v] of Object.entries(value.discriminator.mapping)) {
-        const discriminator = k as string;
-        if (typeof v === "string" && v.charAt(0) === "#") {
-          const ref = v as string;
-          const resolvedRef = parser.byRef(ref);
-          value.discriminator.mapping[discriminator] = resolvedRef;
+      if (
+        value.discriminator.mapping &&
+        typeof value.discriminator.mapping === "object"
+      ) {
+        for (let [k, v] of Object.entries(value.discriminator.mapping)) {
+          const discriminator = k as string;
+          if (typeof v === "string" && v.charAt(0) === "#") {
+            const ref = v as string;
+            const resolvedRef = parser.byRef(ref);
+            value.discriminator.mapping[discriminator] = resolvedRef;
+          }
         }
       }
     }

package/src/sidebars/index.ts

@@ -66,13 +66,12 @@ function groupByTags(
       .filter((item): item is string => !!item)
   );
 
-  // Only include operation tags that are globally defined
-  const apiTags: string[] = [];
+  // Combine globally defined tags with operation tags
+  let apiTags: string[] = [];
   tags.flat().forEach((tag) => {
-    if (operationTags.includes(tag.name!)) {
-      apiTags.push(tag.name!);
-    }
+    apiTags.push(tag.name!);
   });
+  apiTags = uniq(apiTags.concat(operationTags));
 
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")