docusaurus-plugin-openapi-docs 1.4.3 → 1.4.5

package/lib/index.js

@@ -125,7 +125,7 @@ description: "{{{frontMatter.description}}}"
 sidebar_label: Introduction
 {{/api}}
 {{#api}}
-sidebar_label: {{{title}}}
+sidebar_label: "{{{title}}}"
 {{/api}}
 {{^api}}
 sidebar_position: 0
@@ -151,7 +151,7 @@ info_path: {{{infoPath}}}
 id: {{{id}}}
 title: "{{{title}}}"
 description: "{{{frontMatter.description}}}"
-sidebar_label: {{{title}}}
+sidebar_label: "{{{title}}}"
 hide_title: true
 custom_edit_url: null
 ---

package/lib/markdown/createRequestSchema.js

@@ -25,6 +25,9 @@ function mergeAllOf(allOf) {
             example: function () {
                 return true;
             },
+            "x-examples": function () {
+                return true;
+            },
             ignoreAdditionalProperties: true,
         },
     });
@@ -89,14 +92,16 @@ function createAnyOneOf(schema) {
 }
 function createProperties(schema) {
     const discriminator = schema.discriminator;
-    return Object.entries(schema.properties).map(([key, val]) => createEdges({
-        name: key,
-        schema: val,
-        required: Array.isArray(schema.required)
-            ? schema.required.includes(key)
-            : false,
-        discriminator,
-    }));
+    return Object.entries(schema.properties).map(([key, val]) => {
+        return createEdges({
+            name: key,
+            schema: val,
+            required: Array.isArray(schema.required)
+                ? schema.required.includes(key)
+                : false,
+            discriminator,
+        });
+    });
 }
 function createAdditionalProperties(schema) {
     // TODO?:
@@ -440,7 +445,7 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
  * Creates the edges or "leaves" of a schema tree. Edges can branch into sub-nodes with createDetails().
  */
 function createEdges({ name, schema, required, discriminator, }) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const schemaName = (0, schema_1.getSchemaName)(schema);
     if (discriminator !== undefined && discriminator.propertyName === name) {
         return createPropertyDiscriminator(name, "string", schema, discriminator, required);
@@ -488,6 +493,9 @@ function createEdges({ name, schema, required, discriminator, }) {
     if (((_b = schema.items) === null || _b === void 0 ? void 0 : _b.properties) !== undefined) {
         return createDetailsNode(name, schemaName, schema, required);
     }
+    if (((_c = schema.items) === null || _c === void 0 ? void 0 : _c.anyOf) !== undefined || ((_d = schema.items) === null || _d === void 0 ? void 0 : _d.oneOf) !== undefined) {
+        return createDetailsNode(name, schemaName, schema, required);
+    }
     if (schema.readOnly && schema.readOnly === true) {
         return undefined;
     }

package/lib/markdown/createResponseSchema.js

@@ -26,6 +26,9 @@ function mergeAllOf(allOf) {
             example: function () {
                 return true;
             },
+            "x-examples": function () {
+                return true;
+            },
         },
         ignoreAdditionalProperties: true,
     });
@@ -90,14 +93,16 @@ function createAnyOneOf(schema) {
 }
 function createProperties(schema) {
     const discriminator = schema.discriminator;
-    return Object.entries(schema.properties).map(([key, val]) => createEdges({
-        name: key,
-        schema: val,
-        required: Array.isArray(schema.required)
-            ? schema.required.includes(key)
-            : false,
-        discriminator,
-    }));
+    return Object.entries(schema.properties).map(([key, val]) => {
+        return createEdges({
+            name: key,
+            schema: val,
+            required: Array.isArray(schema.required)
+                ? schema.required.includes(key)
+                : false,
+            discriminator,
+        });
+    });
 }
 function createAdditionalProperties(schema) {
     // TODO?:
@@ -439,7 +444,7 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
  * Creates the edges or "leaves" of a schema tree. Edges can branch into sub-nodes with createDetails().
  */
 function createEdges({ name, schema, required, discriminator, }) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const schemaName = (0, schema_1.getSchemaName)(schema);
     if (discriminator !== undefined && discriminator.propertyName === name) {
         return createPropertyDiscriminator(name, "string", schema, discriminator, required);
@@ -487,6 +492,9 @@ function createEdges({ name, schema, required, discriminator, }) {
     if (((_b = schema.items) === null || _b === void 0 ? void 0 : _b.properties) !== undefined) {
         return createDetailsNode(name, schemaName, schema, required);
     }
+    if (((_c = schema.items) === null || _c === void 0 ? void 0 : _c.anyOf) !== undefined || ((_d = schema.items) === null || _d === void 0 ? void 0 : _d.oneOf) !== undefined) {
+        return createDetailsNode(name, schemaName, schema, required);
+    }
     if (schema.writeOnly && schema.writeOnly === true) {
         return undefined;
     }

package/lib/openapi/openapi.js

@@ -19,6 +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 unionBy_1 = __importDefault(require("lodash/unionBy"));
+const uniq_1 = __importDefault(require("lodash/uniq"));
 const index_1 = require("../index");
 const createRequestExample_1 = require("./createRequestExample");
 const loadAndResolveSpec_1 = require("./utils/loadAndResolveSpec");
@@ -64,41 +65,9 @@ function createItems(openapiData, sidebarOptions) {
     // TODO: Find a better way to handle this
     let items = [];
     const infoId = (0, kebabCase_1.default)(openapiData.info.title);
-    if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
-        // Only create an tag pages if categoryLinkSource set to tag.
-        const tags = (_a = openapiData.tags) !== null && _a !== void 0 ? _a : [];
-        // eslint-disable-next-line array-callback-return
-        tags
-            .filter((tag) => { var _a; return !((_a = tag.description) === null || _a === void 0 ? void 0 : _a.includes("SchemaDefinition")); })
-            // eslint-disable-next-line array-callback-return
-            .map((tag) => {
-            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: {
-                    description: splitDescription
-                        ? splitDescription[0]
-                            .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-                            .replace(/\s+$/, "")
-                        : "",
-                },
-                tag: {
-                    ...tag,
-                },
-            };
-            items.push(tagPage);
-        });
-    }
     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;
+        const infoDescription = (_a = openapiData.info) === null || _a === void 0 ? void 0 : _a.description;
         let splitDescription;
         if (infoDescription) {
             splitDescription = infoDescription.match(/[^\r\n]+/g);
@@ -107,7 +76,9 @@ function createItems(openapiData, sidebarOptions) {
             type: "info",
             id: infoId,
             unversionedId: infoId,
-            title: openapiData.info.title,
+            title: openapiData.info.title
+                ? openapiData.info.title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                : "",
             description: openapiData.info.description
                 ? openapiData.info.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                 : "",
@@ -118,11 +89,11 @@ function createItems(openapiData, sidebarOptions) {
                         .replace(/\s+$/, "")
                     : "",
             },
-            securitySchemes: (_c = openapiData.components) === null || _c === void 0 ? void 0 : _c.securitySchemes,
+            securitySchemes: (_b = openapiData.components) === null || _b === void 0 ? void 0 : _b.securitySchemes,
             info: {
                 ...openapiData.info,
                 tags: openapiData.tags,
-                title: (_d = openapiData.info.title) !== null && _d !== void 0 ? _d : "Introduction",
+                title: (_c = openapiData.info.title) !== null && _c !== void 0 ? _c : "Introduction",
                 logo: openapiData.info["x-logo"],
                 darkLogo: openapiData.info["x-dark-logo"],
             },
@@ -132,18 +103,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 = (_f = (_e = operationObject.summary) !== null && _e !== void 0 ? _e : operationObject.operationId) !== null && _f !== void 0 ? _f : "Missing summary";
+            const title = (_e = (_d = operationObject.summary) !== null && _d !== void 0 ? _d : operationObject.operationId) !== null && _e !== void 0 ? _e : "Missing summary";
             if (operationObject.description === undefined) {
                 operationObject.description =
-                    (_h = (_g = operationObject.summary) !== null && _g !== void 0 ? _g : operationObject.operationId) !== null && _h !== void 0 ? _h : "";
+                    (_g = (_f = operationObject.summary) !== null && _f !== void 0 ? _f : operationObject.operationId) !== null && _g !== void 0 ? _g : "";
             }
             const baseId = operationObject.operationId
                 ? (0, kebabCase_1.default)(operationObject.operationId)
                 : (0, kebabCase_1.default)(operationObject.summary);
-            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;
+            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;
             // Add security schemes so we know how to handle security.
-            const securitySchemes = (_m = openapiData.components) === null || _m === void 0 ? void 0 : _m.securitySchemes;
+            const securitySchemes = (_l = openapiData.components) === null || _l === void 0 ? void 0 : _l.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)) {
@@ -153,12 +124,12 @@ function createItems(openapiData, sidebarOptions) {
                 }
             }
             let jsonRequestBodyExample;
-            const body = (_p = (_o = operationObject.requestBody) === null || _o === void 0 ? void 0 : _o.content) === null || _p === void 0 ? void 0 : _p["application/json"];
+            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, createRequestExample_1.sampleRequestFromSchema)(body.schema);
             }
             // Handle vendor JSON media types
-            const bodyContent = (_q = operationObject.requestBody) === null || _q === void 0 ? void 0 : _q.content;
+            const bodyContent = (_p = operationObject.requestBody) === null || _p === void 0 ? void 0 : _p.content;
             if (bodyContent) {
                 const firstBodyContentKey = Object.keys(bodyContent)[0];
                 if (firstBodyContentKey.endsWith("+json")) {
@@ -190,7 +161,7 @@ function createItems(openapiData, sidebarOptions) {
                 id: baseId,
                 infoId: infoId !== null && infoId !== void 0 ? infoId : "",
                 unversionedId: baseId,
-                title: title,
+                title: title ? title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'") : "",
                 description: operationObject.description
                     ? operationObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                     : "",
@@ -216,6 +187,45 @@ function createItems(openapiData, sidebarOptions) {
             items.push(apiPage);
         }
     }
+    if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
+        // Get global tags
+        const tags = (_q = openapiData.tags) !== null && _q !== void 0 ? _q : [];
+        // Get operation tags
+        const apiItems = items.filter((item) => {
+            return item.type === "api";
+        });
+        const operationTags = (0, uniq_1.default)(apiItems
+            .flatMap((item) => item.api.tags)
+            .filter((item) => !!item));
+        // eslint-disable-next-line array-callback-return
+        tags
+            .filter((tag) => operationTags.includes(tag.name)) // include only tags referenced by operation
+            // eslint-disable-next-line array-callback-return
+            .map((tag) => {
+            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: {
+                    description: splitDescription
+                        ? splitDescription[0]
+                            .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                            .replace(/\s+$/, "")
+                        : "",
+                },
+                tag: {
+                    ...tag,
+                },
+            };
+            items.push(tagPage);
+        });
+    }
     return items;
 }
 /**

package/lib/sidebars/index.js

@@ -38,9 +38,13 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
     // Combine globally defined tags with operation tags
+    // Only include global tag if referenced in operation tags
     let apiTags = [];
     tags.flat().forEach((tag) => {
-        apiTags.push(tag.name);
+        // Should we also check x-displayName?
+        if (operationTags.includes(tag.name)) {
+            apiTags.push(tag.name);
+        }
     });
     apiTags = (0, uniq_1.default)(apiTags.concat(operationTags));
     const basePath = docPath

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,8 +28,8 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.1",
-    "@docusaurus/types": "2.0.1",
+    "@docusaurus/module-type-aliases": "^2.0.1",
+    "@docusaurus/types": "^2.0.1",
     "@types/fs-extra": "^9.0.13",
     "@types/js-yaml": "^4.0.5",
     "@types/json-pointer": "^1.0.31",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "277586102253008f831bedbb990fb9854658a190"
+  "gitHead": "84ff5b3176d6734e9ec967131f45e044eca5d108"
 }

package/src/index.ts

@@ -164,7 +164,7 @@ description: "{{{frontMatter.description}}}"
 sidebar_label: Introduction
 {{/api}}
 {{#api}}
-sidebar_label: {{{title}}}
+sidebar_label: "{{{title}}}"
 {{/api}}
 {{^api}}
 sidebar_position: 0
@@ -191,7 +191,7 @@ info_path: {{{infoPath}}}
 id: {{{id}}}
 title: "{{{title}}}"
 description: "{{{frontMatter.description}}}"
-sidebar_label: {{{title}}}
+sidebar_label: "{{{title}}}"
 hide_title: true
 custom_edit_url: null
 ---

package/src/markdown/createRequestSchema.ts

@@ -26,6 +26,9 @@ export function mergeAllOf(allOf: SchemaObject[]) {
       example: function () {
         return true;
       },
+      "x-examples": function () {
+        return true;
+      },
       ignoreAdditionalProperties: true,
     },
   });
@@ -101,16 +104,16 @@ function createAnyOneOf(schema: SchemaObject): any {
 
 function createProperties(schema: SchemaObject) {
   const discriminator = schema.discriminator;
-  return Object.entries(schema.properties!).map(([key, val]) =>
-    createEdges({
+  return Object.entries(schema.properties!).map(([key, val]) => {
+    return createEdges({
       name: key,
       schema: val,
       required: Array.isArray(schema.required)
         ? schema.required.includes(key)
         : false,
       discriminator,
-    })
-  );
+    });
+  });
 }
 
 function createAdditionalProperties(schema: SchemaObject) {
@@ -610,6 +613,10 @@ function createEdges({
     return createDetailsNode(name, schemaName, schema, required);
   }
 
+  if (schema.items?.anyOf !== undefined || schema.items?.oneOf !== undefined) {
+    return createDetailsNode(name, schemaName, schema, required);
+  }
+
   if (schema.readOnly && schema.readOnly === true) {
     return undefined;
   }

package/src/markdown/createResponseSchema.ts

@@ -31,6 +31,9 @@ export function mergeAllOf(allOf: SchemaObject[]) {
       example: function () {
         return true;
       },
+      "x-examples": function () {
+        return true;
+      },
     },
     ignoreAdditionalProperties: true,
   });
@@ -106,16 +109,16 @@ function createAnyOneOf(schema: SchemaObject): any {
 
 function createProperties(schema: SchemaObject) {
   const discriminator = schema.discriminator;
-  return Object.entries(schema.properties!).map(([key, val]) =>
-    createEdges({
+  return Object.entries(schema.properties!).map(([key, val]) => {
+    return createEdges({
       name: key,
       schema: val,
       required: Array.isArray(schema.required)
         ? schema.required.includes(key)
         : false,
       discriminator,
-    })
-  );
+    });
+  });
 }
 
 function createAdditionalProperties(schema: SchemaObject) {
@@ -610,6 +613,10 @@ function createEdges({
     return createDetailsNode(name, schemaName, schema, required);
   }
 
+  if (schema.items?.anyOf !== undefined || schema.items?.oneOf !== undefined) {
+    return createDetailsNode(name, schemaName, schema, required);
+  }
+
   if (schema.writeOnly && schema.writeOnly === true) {
     return undefined;
   }

package/src/openapi/openapi.ts

@@ -16,6 +16,7 @@ import fs from "fs-extra";
 import cloneDeep from "lodash/cloneDeep";
 import kebabCase from "lodash/kebabCase";
 import unionBy from "lodash/unionBy";
+import uniq from "lodash/uniq";
 
 import { isURL } from "../index";
 import {
@@ -85,41 +86,6 @@ function createItems(
   let items: PartialPage<ApiMetadata>[] = [];
   const infoId = kebabCase(openapiData.info.title);
 
-  if (sidebarOptions?.categoryLinkSource === "tag") {
-    // Only create an tag pages if categoryLinkSource set to tag.
-    const tags: TagObject[] = openapiData.tags ?? [];
-    // eslint-disable-next-line array-callback-return
-    tags
-      .filter((tag) => !tag.description?.includes("SchemaDefinition"))
-      // eslint-disable-next-line array-callback-return
-      .map((tag) => {
-        const description = getTagDisplayName(
-          tag.name!,
-          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: {
-            description: splitDescription
-              ? splitDescription[0]
-                  .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-                  .replace(/\s+$/, "")
-              : "",
-          },
-          tag: {
-            ...tag,
-          },
-        };
-        items.push(tagPage);
-      });
-  }
-
   if (openapiData.info.description) {
     // Only create an info page if we have a description.
     const infoDescription = openapiData.info?.description;
@@ -131,7 +97,9 @@ function createItems(
       type: "info",
       id: infoId,
       unversionedId: infoId,
-      title: openapiData.info.title,
+      title: openapiData.info.title
+        ? openapiData.info.title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+        : "",
       description: openapiData.info.description
         ? openapiData.info.description.replace(
             /((?:^|[^\\])(?:\\{2})*)"/g,
@@ -237,7 +205,7 @@ function createItems(
         id: baseId,
         infoId: infoId ?? "",
         unversionedId: baseId,
-        title: title,
+        title: title ? title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'") : "",
         description: operationObject.description
           ? operationObject.description.replace(
               /((?:^|[^\\])(?:\\{2})*)"/g,
@@ -268,6 +236,52 @@ function createItems(
     }
   }
 
+  if (sidebarOptions?.categoryLinkSource === "tag") {
+    // Get global tags
+    const tags: TagObject[] = openapiData.tags ?? [];
+
+    // Get operation tags
+    const apiItems = items.filter((item) => {
+      return item.type === "api";
+    }) as ApiPageMetadata[];
+    const operationTags = uniq(
+      apiItems
+        .flatMap((item) => item.api.tags)
+        .filter((item): item is string => !!item)
+    );
+
+    // eslint-disable-next-line array-callback-return
+    tags
+      .filter((tag) => operationTags.includes(tag.name!)) // include only tags referenced by operation
+      // eslint-disable-next-line array-callback-return
+      .map((tag) => {
+        const description = getTagDisplayName(
+          tag.name!,
+          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: {
+            description: splitDescription
+              ? splitDescription[0]
+                  .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                  .replace(/\s+$/, "")
+              : "",
+          },
+          tag: {
+            ...tag,
+          },
+        };
+        items.push(tagPage);
+      });
+  }
+
   return items as ApiMetadata[];
 }
 

package/src/sidebars/index.ts

@@ -68,9 +68,13 @@ function groupByTags(
   );
 
   // Combine globally defined tags with operation tags
+  // Only include global tag if referenced in operation tags
   let apiTags: string[] = [];
   tags.flat().forEach((tag) => {
-    apiTags.push(tag.name!);
+    // Should we also check x-displayName?
+    if (operationTags.includes(tag.name!)) {
+      apiTags.push(tag.name!);
+    }
   });
   apiTags = uniq(apiTags.concat(operationTags));