docusaurus-plugin-openapi-docs 1.4.1 → 1.4.3

package/lib/index.js

@@ -27,15 +27,18 @@ function getDocsPluginConfig(presetsPlugins, pluginId) {
     // eslint-disable-next-line array-callback-return
     const filteredConfig = presetsPlugins.filter((data) => {
         // Search presets
-        if (data[0].endsWith(pluginId)) {
-            return data[1];
-        }
-        // Search plugin-content-docs instances
-        if (data[0] === "@docusaurus/plugin-content-docs") {
-            const configPluginId = data[1].id ? data[1].id : "default";
-            if (configPluginId === pluginId) {
+        if (Array.isArray(data)) {
+            if (typeof data[0] === "string" && data[0].endsWith(pluginId)) {
                 return data[1];
             }
+            // Search plugin-content-docs instances
+            if (typeof data[0] === "string" &&
+                data[0] === "@docusaurus/plugin-content-docs") {
+                const configPluginId = data[1].id ? data[1].id : "default";
+                if (configPluginId === pluginId) {
+                    return data[1];
+                }
+            }
         }
     })[0];
     if (filteredConfig) {
@@ -117,7 +120,7 @@ function pluginOpenAPIDocs(context, options) {
                 : `---
 id: {{{id}}}
 title: "{{{title}}}"
-description: "{{{description}}}"
+description: "{{{frontMatter.description}}}"
 {{^api}}
 sidebar_label: Introduction
 {{/api}}
@@ -147,7 +150,7 @@ info_path: {{{infoPath}}}
             const infoMdTemplate = `---
 id: {{{id}}}
 title: "{{{title}}}"
-description: "{{{description}}}"
+description: "{{{frontMatter.description}}}"
 sidebar_label: {{{title}}}
 hide_title: true
 custom_edit_url: null
@@ -164,8 +167,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
       `;
             const tagMdTemplate = `---
 id: {{{id}}}
-title: "{{{description}}}"
-description: "{{{description}}}"
+title: "{{{frontMatter.description}}}"
+description: "{{{frontMatter.description}}}"
 custom_edit_url: null
 ---
 
@@ -256,7 +259,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
     }
     async function cleanApiDocs(options) {
         const { outputDir } = options;
-        const apiDir = path_1.default.join(siteDir, outputDir);
+        const apiDir = (0, utils_1.posixPath)(path_1.default.join(siteDir, outputDir));
         const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
             cwd: path_1.default.resolve(apiDir),
             deep: 1,

package/lib/openapi/openapi.js

@@ -60,7 +60,7 @@ async function createPostmanCollection(openapiData) {
     return await jsonToCollection(data);
 }
 function createItems(openapiData, sidebarOptions) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
     // TODO: Find a better way to handle this
     let items = [];
     const infoId = (0, kebabCase_1.default)(openapiData.info.title);
@@ -75,13 +75,20 @@ function createItems(openapiData, sidebarOptions) {
             var _a;
             const description = getTagDisplayName(tag.name, (_a = openapiData.tags) !== null && _a !== void 0 ? _a : []);
             const tagId = (0, kebabCase_1.default)(tag.name);
+            const splitDescription = description.match(/[^\r\n]+/g);
             const tagPage = {
                 type: "tag",
                 id: tagId,
                 unversionedId: tagId,
                 title: description !== null && description !== void 0 ? description : "",
                 description: description !== null && description !== void 0 ? description : "",
-                frontMatter: {},
+                frontMatter: {
+                    description: splitDescription
+                        ? splitDescription[0]
+                            .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                            .replace(/\s+$/, "")
+                        : "",
+                },
                 tag: {
                     ...tag,
                 },
@@ -91,6 +98,11 @@ function createItems(openapiData, sidebarOptions) {
     }
     if (openapiData.info.description) {
         // Only create an info page if we have a description.
+        const infoDescription = (_b = openapiData.info) === null || _b === void 0 ? void 0 : _b.description;
+        let splitDescription;
+        if (infoDescription) {
+            splitDescription = infoDescription.match(/[^\r\n]+/g);
+        }
         const infoPage = {
             type: "info",
             id: infoId,
@@ -99,12 +111,18 @@ function createItems(openapiData, sidebarOptions) {
             description: openapiData.info.description
                 ? openapiData.info.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                 : "",
-            frontMatter: {},
-            securitySchemes: (_b = openapiData.components) === null || _b === void 0 ? void 0 : _b.securitySchemes,
+            frontMatter: {
+                description: splitDescription
+                    ? splitDescription[0]
+                        .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                        .replace(/\s+$/, "")
+                    : "",
+            },
+            securitySchemes: (_c = openapiData.components) === null || _c === void 0 ? void 0 : _c.securitySchemes,
             info: {
                 ...openapiData.info,
                 tags: openapiData.tags,
-                title: (_c = openapiData.info.title) !== null && _c !== void 0 ? _c : "Introduction",
+                title: (_d = openapiData.info.title) !== null && _d !== void 0 ? _d : "Introduction",
                 logo: openapiData.info["x-logo"],
                 darkLogo: openapiData.info["x-dark-logo"],
             },
@@ -114,18 +132,18 @@ function createItems(openapiData, sidebarOptions) {
     for (let [path, pathObject] of Object.entries(openapiData.paths)) {
         const { $ref, description, parameters, servers, summary, ...rest } = pathObject;
         for (let [method, operationObject] of Object.entries({ ...rest })) {
-            const title = (_e = (_d = operationObject.summary) !== null && _d !== void 0 ? _d : operationObject.operationId) !== null && _e !== void 0 ? _e : "Missing summary";
+            const title = (_f = (_e = operationObject.summary) !== null && _e !== void 0 ? _e : operationObject.operationId) !== null && _f !== void 0 ? _f : "Missing summary";
             if (operationObject.description === undefined) {
                 operationObject.description =
-                    (_g = (_f = operationObject.summary) !== null && _f !== void 0 ? _f : operationObject.operationId) !== null && _g !== void 0 ? _g : "";
+                    (_h = (_g = operationObject.summary) !== null && _g !== void 0 ? _g : operationObject.operationId) !== null && _h !== void 0 ? _h : "";
             }
             const baseId = operationObject.operationId
                 ? (0, kebabCase_1.default)(operationObject.operationId)
                 : (0, kebabCase_1.default)(operationObject.summary);
-            const servers = (_j = (_h = operationObject.servers) !== null && _h !== void 0 ? _h : pathObject.servers) !== null && _j !== void 0 ? _j : openapiData.servers;
-            const security = (_k = operationObject.security) !== null && _k !== void 0 ? _k : openapiData.security;
+            const servers = (_k = (_j = operationObject.servers) !== null && _j !== void 0 ? _j : pathObject.servers) !== null && _k !== void 0 ? _k : openapiData.servers;
+            const security = (_l = operationObject.security) !== null && _l !== void 0 ? _l : openapiData.security;
             // Add security schemes so we know how to handle security.
-            const securitySchemes = (_l = openapiData.components) === null || _l === void 0 ? void 0 : _l.securitySchemes;
+            const securitySchemes = (_m = openapiData.components) === null || _m === void 0 ? void 0 : _m.securitySchemes;
             // Make sure schemes are lowercase. See: https://github.com/cloud-annotations/docusaurus-plugin-openapi/issues/79
             if (securitySchemes) {
                 for (let securityScheme of Object.values(securitySchemes)) {
@@ -135,12 +153,12 @@ 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"];
+            const body = (_p = (_o = operationObject.requestBody) === null || _o === void 0 ? void 0 : _o.content) === null || _p === void 0 ? void 0 : _p["application/json"];
             if (body === null || body === void 0 ? void 0 : 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;
+            const bodyContent = (_q = operationObject.requestBody) === null || _q === void 0 ? void 0 : _q.content;
             if (bodyContent) {
                 const firstBodyContentKey = Object.keys(bodyContent)[0];
                 if (firstBodyContentKey.endsWith("+json")) {
@@ -162,6 +180,11 @@ function createItems(openapiData, sidebarOptions) {
                     defaults.parameters = parameters;
                 }
             }
+            const opDescription = operationObject.description;
+            let splitDescription;
+            if (opDescription) {
+                splitDescription = opDescription.match(/[^\r\n]+/g);
+            }
             const apiPage = {
                 type: "api",
                 id: baseId,
@@ -171,7 +194,13 @@ function createItems(openapiData, sidebarOptions) {
                 description: operationObject.description
                     ? operationObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                     : "",
-                frontMatter: {},
+                frontMatter: {
+                    description: splitDescription
+                        ? splitDescription[0]
+                            .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                            .replace(/\s+$/, "")
+                        : "",
+                },
                 api: {
                     ...defaults,
                     tags: operationObject.tags,
@@ -222,7 +251,7 @@ async function readOpenapiFiles(openapiPath, options) {
             const sources = allFiles.filter((x) => !x.includes("_category_")); // todo: regex exclude?
             return Promise.all(sources.map(async (source) => {
                 // TODO: make a function for this
-                const fullPath = path_1.default.join(openapiPath, source);
+                const fullPath = (0, utils_1.posixPath)(path_1.default.join(openapiPath, source));
                 const data = (await (0, loadAndResolveSpec_1.loadAndResolveSpec)(fullPath));
                 return {
                     source: fullPath,

package/lib/openapi/openapi.test.js

@@ -10,12 +10,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const path_1 = __importDefault(require("path"));
+const utils_1 = require("@docusaurus/utils");
 const _1 = require(".");
 // npx jest packages/docusaurus-plugin-openapi/src/openapi/openapi.test.ts --watch
 describe("openapi", () => {
     describe("readOpenapiFiles", () => {
         it("readOpenapiFiles", async () => {
-            const results = await (0, _1.readOpenapiFiles)(path_1.default.join(__dirname, "__fixtures__/examples"), { specPath: "./", outputDir: "./" });
+            const results = await (0, _1.readOpenapiFiles)((0, utils_1.posixPath)(path_1.default.join(__dirname, "__fixtures__/examples")), { specPath: "./", outputDir: "./" });
             const categoryMeta = results.find((x) => x.source.endsWith("_category_.json"));
             expect(categoryMeta).toBeFalsy();
             // console.log(results);

package/lib/sidebars/index.js

@@ -10,6 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const path_1 = __importDefault(require("path"));
+const utils_1 = require("@docusaurus/utils");
 const clsx_1 = __importDefault(require("clsx"));
 const lodash_1 = require("lodash");
 const uniq_1 = __importDefault(require("lodash/uniq"));
@@ -74,7 +75,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
         .map((tag) => {
         var _a;
         // Map info object to tag
-        const taggedInfoObject = intros.find((i) => i.tags ? i.tags.includes(tag) : undefined);
+        const taggedInfoObject = intros.find((i) => i.tags ? i.tags.find((t) => t.name === tag) : undefined);
         const tagObject = tags.flat().find((t) => {
             var _a;
             return (_a = tag === t.name) !== null && _a !== void 0 ? _a : {
@@ -106,8 +107,8 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
                 type: "generated-index",
                 title: tag,
                 slug: label
-                    ? path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(label), (0, lodash_1.kebabCase)(tag))
-                    : path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(tag)),
+                    ? (0, utils_1.posixPath)(path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(label), (0, lodash_1.kebabCase)(tag)))
+                    : (0, utils_1.posixPath)(path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(tag))),
             };
         }
         return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "ddfa49093f75f628536b8d9e25f88eb9e541667c"
+  "gitHead": "277586102253008f831bedbb990fb9854658a190"
 }

package/src/index.ts

@@ -9,7 +9,7 @@ import fs from "fs";
 import path from "path";
 
 import type { LoadContext, Plugin } from "@docusaurus/types";
-import { Globby } from "@docusaurus/utils";
+import { Globby, posixPath } from "@docusaurus/utils";
 import chalk from "chalk";
 import { render } from "mustache";
 
@@ -30,18 +30,24 @@ export function getDocsPluginConfig(
   // eslint-disable-next-line array-callback-return
   const filteredConfig = presetsPlugins.filter((data) => {
     // Search presets
-    if (data[0].endsWith(pluginId)) {
-      return data[1];
-    }
-
-    // Search plugin-content-docs instances
-    if (data[0] === "@docusaurus/plugin-content-docs") {
-      const configPluginId = data[1].id ? data[1].id : "default";
-      if (configPluginId === pluginId) {
+    if (Array.isArray(data)) {
+      if (typeof data[0] === "string" && data[0].endsWith(pluginId)) {
         return data[1];
       }
+
+      // Search plugin-content-docs instances
+      if (
+        typeof data[0] === "string" &&
+        data[0] === "@docusaurus/plugin-content-docs"
+      ) {
+        const configPluginId = data[1].id ? data[1].id : "default";
+        if (configPluginId === pluginId) {
+          return data[1];
+        }
+      }
     }
   })[0];
+
   if (filteredConfig) {
     // Search presets, e.g. "classic"
     if (filteredConfig[0].endsWith(pluginId)) {
@@ -153,7 +159,7 @@ export default function pluginOpenAPIDocs(
         : `---
 id: {{{id}}}
 title: "{{{title}}}"
-description: "{{{description}}}"
+description: "{{{frontMatter.description}}}"
 {{^api}}
 sidebar_label: Introduction
 {{/api}}
@@ -184,7 +190,7 @@ info_path: {{{infoPath}}}
       const infoMdTemplate = `---
 id: {{{id}}}
 title: "{{{title}}}"
-description: "{{{description}}}"
+description: "{{{frontMatter.description}}}"
 sidebar_label: {{{title}}}
 hide_title: true
 custom_edit_url: null
@@ -202,8 +208,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
       const tagMdTemplate = `---
 id: {{{id}}}
-title: "{{{description}}}"
-description: "{{{description}}}"
+title: "{{{frontMatter.description}}}"
+description: "{{{frontMatter.description}}}"
 custom_edit_url: null
 ---
 
@@ -332,7 +338,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
   async function cleanApiDocs(options: APIOptions) {
     const { outputDir } = options;
-    const apiDir = path.join(siteDir, outputDir);
+    const apiDir = posixPath(path.join(siteDir, outputDir));
     const apiMdxFiles = await Globby(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
       cwd: path.resolve(apiDir),
       deep: 1,

package/src/openapi/openapi.test.ts

@@ -7,6 +7,8 @@
 
 import path from "path";
 
+import { posixPath } from "@docusaurus/utils";
+
 import { readOpenapiFiles } from ".";
 
 // npx jest packages/docusaurus-plugin-openapi/src/openapi/openapi.test.ts --watch
@@ -15,7 +17,7 @@ describe("openapi", () => {
   describe("readOpenapiFiles", () => {
     it("readOpenapiFiles", async () => {
       const results = await readOpenapiFiles(
-        path.join(__dirname, "__fixtures__/examples"),
+        posixPath(path.join(__dirname, "__fixtures__/examples")),
         { specPath: "./", outputDir: "./" }
       );
       const categoryMeta = results.find((x) =>

package/src/openapi/openapi.ts

@@ -7,7 +7,7 @@
 
 import path from "path";
 
-import { Globby, GlobExcludeDefault } from "@docusaurus/utils";
+import { Globby, GlobExcludeDefault, posixPath } from "@docusaurus/utils";
 import Converter from "@paloaltonetworks/openapi-to-postmanv2";
 import sdk from "@paloaltonetworks/postman-collection";
 import Collection from "@paloaltonetworks/postman-collection";
@@ -98,13 +98,20 @@ function createItems(
           openapiData.tags ?? []
         );
         const tagId = kebabCase(tag.name);
+        const splitDescription = description.match(/[^\r\n]+/g);
         const tagPage: PartialPage<TagPageMetadata> = {
           type: "tag",
           id: tagId,
           unversionedId: tagId,
           title: description ?? "",
           description: description ?? "",
-          frontMatter: {},
+          frontMatter: {
+            description: splitDescription
+              ? splitDescription[0]
+                  .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                  .replace(/\s+$/, "")
+              : "",
+          },
           tag: {
             ...tag,
           },
@@ -115,6 +122,11 @@ function createItems(
 
   if (openapiData.info.description) {
     // Only create an info page if we have a description.
+    const infoDescription = openapiData.info?.description;
+    let splitDescription: any;
+    if (infoDescription) {
+      splitDescription = infoDescription.match(/[^\r\n]+/g);
+    }
     const infoPage: PartialPage<InfoPageMetadata> = {
       type: "info",
       id: infoId,
@@ -126,7 +138,13 @@ function createItems(
             "$1'"
           )
         : "",
-      frontMatter: {},
+      frontMatter: {
+        description: splitDescription
+          ? splitDescription[0]
+              .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+              .replace(/\s+$/, "")
+          : "",
+      },
       securitySchemes: openapiData.components?.securitySchemes,
       info: {
         ...openapiData.info,
@@ -208,6 +226,12 @@ function createItems(
         }
       }
 
+      const opDescription = operationObject.description;
+      let splitDescription: any;
+      if (opDescription) {
+        splitDescription = opDescription.match(/[^\r\n]+/g);
+      }
+
       const apiPage: PartialPage<ApiPageMetadata> = {
         type: "api",
         id: baseId,
@@ -220,7 +244,13 @@ function createItems(
               "$1'"
             )
           : "",
-        frontMatter: {},
+        frontMatter: {
+          description: splitDescription
+            ? splitDescription[0]
+                .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                .replace(/\s+$/, "")
+            : "",
+        },
         api: {
           ...defaults,
           tags: operationObject.tags,
@@ -290,7 +320,7 @@ export async function readOpenapiFiles(
       return Promise.all(
         sources.map(async (source) => {
           // TODO: make a function for this
-          const fullPath = path.join(openapiPath, source);
+          const fullPath = posixPath(path.join(openapiPath, source));
           const data = (await loadAndResolveSpec(
             fullPath
           )) as unknown as OpenApiObject;

package/src/sidebars/index.ts

@@ -13,6 +13,7 @@ import {
   SidebarItemCategoryLinkConfig,
   SidebarItemDoc,
 } from "@docusaurus/plugin-content-docs/src/sidebars/types";
+import { posixPath } from "@docusaurus/utils";
 import clsx from "clsx";
 import { kebabCase } from "lodash";
 import uniq from "lodash/uniq";
@@ -110,7 +111,7 @@ function groupByTags(
     .map((tag) => {
       // Map info object to tag
       const taggedInfoObject = intros.find((i) =>
-        i.tags ? i.tags.includes(tag) : undefined
+        i.tags ? i.tags.find((t: any) => t.name === tag) : undefined
       );
       const tagObject = tags.flat().find(
         (t) =>
@@ -148,8 +149,15 @@ function groupByTags(
           type: "generated-index" as "generated-index",
           title: tag,
           slug: label
-            ? path.join("/category", basePath, kebabCase(label), kebabCase(tag))
-            : path.join("/category", basePath, kebabCase(tag)),
+            ? posixPath(
+                path.join(
+                  "/category",
+                  basePath,
+                  kebabCase(label),
+                  kebabCase(tag)
+                )
+              )
+            : posixPath(path.join("/category", basePath, kebabCase(tag))),
         } as SidebarItemCategoryLinkConfig;
       }