docusaurus-plugin-openapi-docs 4.5.0 → 4.6.0

package/lib/openapi/createSchemaExample.test.js

@@ -0,0 +1,48 @@
+"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.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+const createSchemaExample_1 = require("./createSchemaExample");
+describe("sampleFromSchema", () => {
+    describe("const support", () => {
+        it("should return default string value when const is not present", () => {
+            const schema = {
+                type: "string",
+            };
+            const context = { type: "request" };
+            const result = (0, createSchemaExample_1.sampleFromSchema)(schema, context);
+            expect(result).toBe("string");
+        });
+        it("should return const value when const is present", () => {
+            const schema = {
+                type: "string",
+                const: "example",
+            };
+            const context = { type: "request" };
+            const result = (0, createSchemaExample_1.sampleFromSchema)(schema, context);
+            expect(result).toBe("example");
+        });
+        it("should handle anyOf with const values", () => {
+            const schema = {
+                type: "string",
+                anyOf: [
+                    {
+                        type: "string",
+                        const: "dog",
+                    },
+                    {
+                        type: "string",
+                        const: "cat",
+                    },
+                ],
+            };
+            const context = { type: "request" };
+            const result = (0, createSchemaExample_1.sampleFromSchema)(schema, context);
+            expect(result).toBe("dog");
+        });
+    });
+});

package/lib/openapi/openapi.js

@@ -65,11 +65,16 @@ const loadAndResolveSpec_1 = require("./utils/loadAndResolveSpec");
  */
 function jsonToCollection(data) {
     return new Promise((resolve, reject) => {
+        var _a, _b;
         let schemaPack = new openapi_to_postmanv2_1.default.SchemaPack({ type: "json", data }, { schemaFaker: false });
         schemaPack.computedOptions.schemaFaker = false;
+        // Make sure the schema was properly validated or reject with error
+        if (!((_a = schemaPack.validationResult) === null || _a === void 0 ? void 0 : _a.result)) {
+            return reject((_b = schemaPack.validationResult) === null || _b === void 0 ? void 0 : _b.reason);
+        }
         schemaPack.convert((_err, conversionResult) => {
-            if (!conversionResult.result) {
-                return reject(conversionResult.reason);
+            if (_err || !conversionResult.result) {
+                return reject(_err || conversionResult.reason);
             }
             return resolve(new sdk.Collection(conversionResult.output[0].data));
         });
@@ -98,13 +103,15 @@ async function createPostmanCollection(openapiData) {
     return await jsonToCollection(data);
 }
 function createItems(openapiData, options, sidebarOptions) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7, _8;
     // TODO: Find a better way to handle this
     let items = [];
     const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
     const infoId = (0, kebabCase_1.default)(infoIdSpaces);
-    if (openapiData.info.description || openapiData.info.title) {
-        // Only create an info page if we have a description.
+    const schemasOnly = (options === null || options === void 0 ? void 0 : options.schemasOnly) === true;
+    // Only create an info page if we have a description/title AND showInfoPage is not false
+    if ((openapiData.info.description || openapiData.info.title) &&
+        (options === null || options === void 0 ? void 0 : options.showInfoPage) !== false) {
         const infoDescription = (_a = openapiData.info) === null || _a === void 0 ? void 0 : _a.description;
         let splitDescription;
         if (infoDescription) {
@@ -231,6 +238,9 @@ function createItems(openapiData, options, sidebarOptions) {
                     ...((options === null || options === void 0 ? void 0 : options.showExtensions) && {
                         show_extensions: options.showExtensions,
                     }),
+                    ...((options === null || options === void 0 ? void 0 : options.maskCredentials) === false && {
+                        mask_credentials_disabled: true,
+                    }),
                 },
                 api: {
                     ...defaults,
@@ -251,10 +261,15 @@ function createItems(openapiData, options, sidebarOptions) {
     }
     // Gather x-webhooks endpoints
     for (let [path, pathObject] of Object.entries((_q = (_p = openapiData["x-webhooks"]) !== null && _p !== void 0 ? _p : openapiData["webhooks"]) !== null && _q !== void 0 ? _q : {})) {
+        const eventName = path;
         path = "webhook";
         const { $ref, description, parameters, servers, summary, ...rest } = pathObject;
         for (let [method, operationObject] of Object.entries({ ...rest })) {
             method = "event";
+            if (operationObject.summary === undefined &&
+                operationObject.operationId === undefined) {
+                operationObject.summary = eventName;
+            }
             const title = (_s = (_r = operationObject.summary) !== null && _r !== void 0 ? _r : operationObject.operationId) !== null && _s !== void 0 ? _s : "Missing summary";
             if (operationObject.description === undefined) {
                 operationObject.description =
@@ -262,7 +277,7 @@ function createItems(openapiData, options, sidebarOptions) {
             }
             const baseId = operationObject.operationId
                 ? (0, kebabCase_1.default)(operationObject.operationId)
-                : (0, kebabCase_1.default)(operationObject.summary);
+                : (0, kebabCase_1.default)((_v = operationObject.summary) !== null && _v !== void 0 ? _v : eventName);
             const extensions = [];
             const commonExtensions = ["x-codeSamples"];
             for (const [key, value] of Object.entries(operationObject)) {
@@ -270,10 +285,10 @@ function createItems(openapiData, options, sidebarOptions) {
                     extensions.push({ key, value });
                 }
             }
-            const servers = (_w = (_v = operationObject.servers) !== null && _v !== void 0 ? _v : pathObject.servers) !== null && _w !== void 0 ? _w : openapiData.servers;
-            const security = (_x = operationObject.security) !== null && _x !== void 0 ? _x : openapiData.security;
+            const servers = (_x = (_w = operationObject.servers) !== null && _w !== void 0 ? _w : pathObject.servers) !== null && _x !== void 0 ? _x : openapiData.servers;
+            const security = (_y = operationObject.security) !== null && _y !== void 0 ? _y : openapiData.security;
             // Add security schemes so we know how to handle security.
-            const securitySchemes = (_y = openapiData.components) === null || _y === void 0 ? void 0 : _y.securitySchemes;
+            const securitySchemes = (_z = openapiData.components) === null || _z === void 0 ? void 0 : _z.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)) {
@@ -283,7 +298,7 @@ function createItems(openapiData, options, sidebarOptions) {
                 }
             }
             let jsonRequestBodyExample;
-            const content = (_z = operationObject.requestBody) === null || _z === void 0 ? void 0 : _z.content;
+            const content = (_0 = operationObject.requestBody) === null || _0 === void 0 ? void 0 : _0.content;
             let body;
             for (let key in content) {
                 if (key.toLowerCase() === "application/json" ||
@@ -296,7 +311,7 @@ function createItems(openapiData, options, sidebarOptions) {
                 jsonRequestBodyExample = (0, createRequestExample_1.sampleRequestFromSchema)(body.schema);
             }
             // Handle vendor JSON media types
-            const bodyContent = (_0 = operationObject.requestBody) === null || _0 === void 0 ? void 0 : _0.content;
+            const bodyContent = (_1 = operationObject.requestBody) === null || _1 === void 0 ? void 0 : _1.content;
             if (bodyContent) {
                 const firstBodyContentKey = Object.keys(bodyContent)[0];
                 if (firstBodyContentKey.endsWith("+json")) {
@@ -345,6 +360,9 @@ function createItems(openapiData, options, sidebarOptions) {
                     ...((options === null || options === void 0 ? void 0 : options.showExtensions) && {
                         show_extensions: options.showExtensions,
                     }),
+                    ...((options === null || options === void 0 ? void 0 : options.maskCredentials) === false && {
+                        mask_credentials_disabled: true,
+                    }),
                 },
                 api: {
                     ...defaults,
@@ -362,14 +380,17 @@ function createItems(openapiData, options, sidebarOptions) {
             items.push(apiPage);
         }
     }
-    if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
-        Object.entries((_2 = (_1 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _1 === void 0 ? void 0 : _1.schemas) !== null && _2 !== void 0 ? _2 : {})
+    if (schemasOnly ||
+        (options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
+        Object.entries((_3 = (_2 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _2 === void 0 ? void 0 : _2.schemas) !== null && _3 !== void 0 ? _3 : {})
             .flatMap(([_, s]) => s["x-tags"])
             .filter((item) => !!item).length > 0) {
         // Gather schemas
-        for (let [schema, schemaObject] of Object.entries((_4 = (_3 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _3 === void 0 ? void 0 : _3.schemas) !== null && _4 !== void 0 ? _4 : {})) {
-            if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true || schemaObject["x-tags"]) {
-                const baseIdSpaces = (_6 = (_5 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _5 === void 0 ? void 0 : _5.replace(" ", "-").toLowerCase()) !== null && _6 !== void 0 ? _6 : "";
+        for (let [schema, schemaObject] of Object.entries((_5 = (_4 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _4 === void 0 ? void 0 : _4.schemas) !== null && _5 !== void 0 ? _5 : {})) {
+            if (schemasOnly ||
+                (options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
+                schemaObject["x-tags"]) {
+                const baseIdSpaces = (_7 = (_6 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _6 === void 0 ? void 0 : _6.replace(" ", "-").toLowerCase()) !== null && _7 !== void 0 ? _7 : "";
                 const baseId = (0, kebabCase_1.default)(baseIdSpaces);
                 const schemaDescription = schemaObject.description;
                 let splitDescription;
@@ -403,7 +424,7 @@ function createItems(openapiData, options, sidebarOptions) {
     }
     if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
         // Get global tags
-        const tags = (_7 = openapiData.tags) !== null && _7 !== void 0 ? _7 : [];
+        const tags = (_8 = openapiData.tags) !== null && _8 !== void 0 ? _8 : [];
         // Get operation tags
         const apiItems = items.filter((item) => {
             return item.type === "api";

package/lib/openapi/openapi.test.js

@@ -13,6 +13,7 @@ const path_1 = __importDefault(require("path"));
 // eslint-disable-next-line import/no-extraneous-dependencies
 const utils_1 = require("@docusaurus/utils");
 const _1 = require(".");
+const openapi_1 = require("./openapi");
 // npx jest packages/docusaurus-plugin-openapi/src/openapi/openapi.test.ts --watch
 describe("openapi", () => {
     describe("readOpenapiFiles", () => {
@@ -30,4 +31,51 @@ describe("openapi", () => {
             expect((_b = (_a = yaml === null || yaml === void 0 ? void 0 : yaml.data.components) === null || _a === void 0 ? void 0 : _a.schemas) === null || _b === void 0 ? void 0 : _b.HelloString["x-tags"]).toBeDefined();
         });
     });
+    describe("schemasOnly", () => {
+        it("includes schema metadata when showSchemas is disabled", async () => {
+            const openapiData = {
+                openapi: "3.0.0",
+                info: {
+                    title: "Schema Only",
+                    version: "1.0.0",
+                },
+                paths: {
+                    "/ping": {
+                        get: {
+                            summary: "Ping",
+                            responses: {
+                                "200": {
+                                    description: "OK",
+                                },
+                            },
+                        },
+                    },
+                },
+                components: {
+                    schemas: {
+                        WithoutTags: {
+                            title: "Without Tags",
+                            type: "object",
+                            properties: {
+                                value: {
+                                    type: "string",
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const options = {
+                specPath: "dummy", // required by the type but unused in this context
+                outputDir: "build",
+                showSchemas: false,
+                schemasOnly: true,
+            };
+            const sidebarOptions = {};
+            const [items] = await (0, openapi_1.processOpenapiFile)(openapiData, options, sidebarOptions);
+            const schemaItems = items.filter((item) => item.type === "schema");
+            expect(schemaItems).toHaveLength(1);
+            expect(schemaItems[0].id).toBe("without-tags");
+        });
+    });
 });

package/lib/openapi/webhooks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/openapi/webhooks.test.js

@@ -0,0 +1,23 @@
+"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 });
+const path_1 = __importDefault(require("path"));
+// eslint-disable-next-line import/no-extraneous-dependencies
+const utils_1 = require("@docusaurus/utils");
+const _1 = require(".");
+describe("webhooks", () => {
+    it("uses event name when summary and operationId are missing", async () => {
+        const files = await (0, _1.readOpenapiFiles)((0, utils_1.posixPath)(path_1.default.join(__dirname, "__fixtures__/webhook/openapi.yaml")));
+        const [items] = await (0, _1.processOpenapiFiles)(files, { specPath: "", outputDir: "" }, {});
+        const webhookItem = items.find((item) => item.type === "api");
+        expect(webhookItem === null || webhookItem === void 0 ? void 0 : webhookItem.id).toBe("order-created");
+    });
+});

package/lib/options.js

@@ -44,7 +44,10 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         sidebarOptions: sidebarOptions,
         markdownGenerators: markdownGenerators,
         showSchemas: utils_validation_1.Joi.boolean(),
+        showInfoPage: utils_validation_1.Joi.boolean(),
+        schemasOnly: utils_validation_1.Joi.boolean(),
         disableCompression: utils_validation_1.Joi.boolean(),
+        maskCredentials: utils_validation_1.Joi.boolean(),
         version: utils_validation_1.Joi.string().when("versions", {
             is: utils_validation_1.Joi.exist(),
             then: utils_validation_1.Joi.required(),

package/lib/sidebars/index.js

@@ -81,9 +81,18 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
     if (sidebarOptions.groupPathsBy !== "tagGroup") {
         apiTags = (0, uniq_1.default)(apiTags.concat(operationTags, schemaTags));
     }
-    const basePath = docPath
-        ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
-        : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
+    // Extract base path from outputDir, handling cases where docPath may not be in outputDir
+    const getBasePathFromOutput = (output, doc) => {
+        var _a, _b;
+        if (doc && output.includes(doc)) {
+            return (_b = (_a = output.split(doc)[1]) === null || _a === void 0 ? void 0 : _a.replace(/^\/+/g, "")) !== null && _b !== void 0 ? _b : "";
+        }
+        const slashIndex = output.indexOf("/", 1);
+        return slashIndex === -1
+            ? ""
+            : output.slice(slashIndex).replace(/^\/+/g, "");
+    };
+    const basePath = getBasePathFromOutput(outputDir, docPath);
     const createDocItemFnContext = {
         sidebarOptions,
         basePath,

package/lib/types.d.ts

@@ -1,6 +1,6 @@
-import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
+import type { SidebarItemDoc } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
 import { InfoObject, OperationObject, SchemaObject, SecuritySchemeObject, TagObject } from "./openapi/types";
-export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
+export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
 export interface PluginOptions {
     id?: string;
     docsPlugin?: string;
@@ -29,7 +29,10 @@ export interface APIOptions {
     proxy?: string;
     markdownGenerators?: MarkdownGenerator;
     showSchemas?: boolean;
+    showInfoPage?: boolean;
+    schemasOnly?: boolean;
     disableCompression?: boolean;
+    maskCredentials?: boolean;
 }
 export interface MarkdownGenerator {
     createApiPageMD?: (pageData: ApiPageMetadata) => string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -32,29 +32,29 @@
     "@docusaurus/types": "^3.5.0",
     "@docusaurus/utils": "^3.5.0",
     "@docusaurus/utils-validation": "^3.5.0",
-    "@types/fs-extra": "^9.0.13",
-    "@types/json-pointer": "^1.0.31",
-    "@types/json-schema": "^7.0.9",
-    "@types/lodash": "^4.14.176",
-    "@types/mustache": "^4.1.2",
-    "eslint-plugin-prettier": "^5.0.1"
+    "@types/fs-extra": "^11.0.4",
+    "@types/json-pointer": "^1.0.34",
+    "@types/json-schema": "^7.0.15",
+    "@types/lodash": "^4.17.20",
+    "@types/mustache": "^4.2.6",
+    "eslint-plugin-prettier": "^5.5.1"
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.5.4",
-    "@redocly/openapi-core": "^1.10.5",
+    "@redocly/openapi-core": "^1.34.3",
     "allof-merge": "^0.6.6",
     "chalk": "^4.1.2",
-    "clsx": "^1.1.1",
-    "fs-extra": "^9.0.1",
+    "clsx": "^2.1.1",
+    "fs-extra": "^11.3.0",
     "json-pointer": "^0.6.2",
     "json5": "^2.2.3",
-    "lodash": "^4.17.20",
+    "lodash": "^4.17.21",
     "mustache": "^4.2.0",
-    "openapi-to-postmanv2": "^4.21.0",
-    "postman-collection": "^4.4.0",
-    "slugify": "^1.6.5",
+    "openapi-to-postmanv2": "^5.0.0",
+    "postman-collection": "^5.0.2",
+    "slugify": "^1.6.6",
     "swagger2openapi": "^7.0.8",
-    "xml-formatter": "^2.6.1"
+    "xml-formatter": "^3.6.6"
   },
   "peerDependencies": {
     "@docusaurus/plugin-content-docs": "^3.5.0",
@@ -65,5 +65,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "cb0ed6e02d7a963d51073e2bfd78d944fbb7ee34"
+  "gitHead": "c7c5ca9934031d166faa0740746ef1a39e72982d"
 }