docusaurus-plugin-openapi-docs 2.0.0-beta.2 → 2.0.0-beta.4

package/lib/markdown/createVendorExtensions.js

@@ -0,0 +1,25 @@
+"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 });
+exports.createVendorExtensions = void 0;
+function createVendorExtensions(extensions) {
+    if (!extensions || typeof extensions !== "object") {
+        return undefined;
+    }
+    const rows = [];
+    extensions.map((extension) => {
+        const extensionRow = () => {
+            return `${extension.key}: ${JSON.stringify(extension.value)}`;
+        };
+        return rows.push(extensionRow());
+    });
+    return `\n\n\`\`\`
+${rows.join("\n")}
+\`\`\`\n\n`;
+}
+exports.createVendorExtensions = createVendorExtensions;

package/lib/markdown/index.d.ts

@@ -1,4 +1,4 @@
 import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
-export declare function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, parameters, requestBody, responses, }, }: ApiPageMetadata): string;
+export declare function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, extensions, parameters, requestBody, responses, }, infoPath, frontMatter, }: ApiPageMetadata): string;
 export declare function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, downloadUrl, }: InfoPageMetadata): string;
 export declare function createTagPageMD({ tag: { description } }: TagPageMetadata): string;

package/lib/markdown/index.js

@@ -8,6 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTagPageMD = exports.createInfoPageMD = exports.createApiPageMD = void 0;
 const createAuthentication_1 = require("./createAuthentication");
+const createAuthorization_1 = require("./createAuthorization");
 const createContactInfo_1 = require("./createContactInfo");
 const createDeprecationNotice_1 = require("./createDeprecationNotice");
 const createDescription_1 = require("./createDescription");
@@ -18,15 +19,18 @@ const createLogo_1 = require("./createLogo");
 const createMethodEndpoint_1 = require("./createMethodEndpoint");
 const createParamsDetails_1 = require("./createParamsDetails");
 const createRequestBodyDetails_1 = require("./createRequestBodyDetails");
+const createRequestHeader_1 = require("./createRequestHeader");
 const createStatusCodes_1 = require("./createStatusCodes");
 const createTermsOfService_1 = require("./createTermsOfService");
+const createVendorExtensions_1 = require("./createVendorExtensions");
 const createVersionBadge_1 = require("./createVersionBadge");
 const utils_1 = require("./utils");
-function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, parameters, requestBody, responses, }, }) {
+function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, extensions, parameters, requestBody, responses, }, infoPath, frontMatter, }) {
     return (0, utils_1.render)([
         `import ApiTabs from "@theme/ApiTabs";\n`,
         `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
-        `import MethodEndpoint from "@theme/ApiDemoPanel/MethodEndpoint";\n`,
+        `import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";\n`,
+        `import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";\n`,
         `import MimeTabs from "@theme/MimeTabs";\n`,
         `import ParamsItem from "@theme/ParamsItem";\n`,
         `import ResponseSamples from "@theme/ResponseSamples";\n`,
@@ -35,14 +39,17 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import TabItem from "@theme/TabItem";\n\n`,
         (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
         (0, createMethodEndpoint_1.createMethodEndpoint)(method, path),
+        infoPath && (0, createAuthorization_1.createAuthorization)(infoPath),
+        frontMatter.show_extensions && (0, createVendorExtensions_1.createVendorExtensions)(extensions),
         (0, createDeprecationNotice_1.createDeprecationNotice)({ deprecated, description: deprecatedDescription }),
         (0, createDescription_1.createDescription)(description),
+        (0, createRequestHeader_1.createRequestHeader)("Request"),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "path" }),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "query" }),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "header" }),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "cookie" }),
         (0, createRequestBodyDetails_1.createRequestBodyDetails)({
-            title: "Request Body",
+            title: "Body",
             body: requestBody,
         }),
         (0, createStatusCodes_1.createStatusCodes)({ responses }),
@@ -54,7 +61,7 @@ function createInfoPageMD({ info: { title, version, description, contact, licens
         `import ApiLogo from "@theme/ApiLogo";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import TabItem from "@theme/TabItem";\n`,
-        `import Export from "@theme/ApiDemoPanel/Export";\n\n`,
+        `import Export from "@theme/ApiExplorer/Export";\n\n`,
         (0, createVersionBadge_1.createVersionBadge)(version),
         (0, createDownload_1.createDownload)(downloadUrl),
         (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),

package/lib/openapi/createRequestExample.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sampleRequestFromSchema = void 0;
 const chalk_1 = __importDefault(require("chalk"));
 const merge_1 = __importDefault(require("lodash/merge"));
-const createRequestSchema_1 = require("../markdown/createRequestSchema");
+const createSchema_1 = require("../markdown/createSchema");
 const primitives = {
     string: {
         default: () => "string",
@@ -51,7 +51,7 @@ function sampleRequestFromProp(name, prop, obj) {
         obj[name] = (0, exports.sampleRequestFromSchema)(prop.anyOf[0]);
     }
     else if (prop.allOf) {
-        const { mergedSchemas } = (0, createRequestSchema_1.mergeAllOf)(prop.allOf);
+        const { mergedSchemas } = (0, createSchema_1.mergeAllOf)(prop.allOf);
         sampleRequestFromProp(name, mergedSchemas, obj);
     }
     else {
@@ -86,7 +86,7 @@ const sampleRequestFromSchema = (schema = {}) => {
             return (0, exports.sampleRequestFromSchema)(anyOf[0]);
         }
         if (allOf) {
-            const { mergedSchemas } = (0, createRequestSchema_1.mergeAllOf)(allOf);
+            const { mergedSchemas } = (0, createSchema_1.mergeAllOf)(allOf);
             if (mergedSchemas.properties) {
                 for (const [key, value] of Object.entries(mergedSchemas.properties)) {
                     if ((value.readOnly && value.readOnly === true) || value.deprecated) {

package/lib/openapi/createResponseExample.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sampleResponseFromSchema = void 0;
 const chalk_1 = __importDefault(require("chalk"));
 const merge_1 = __importDefault(require("lodash/merge"));
-const createResponseSchema_1 = require("../markdown/createResponseSchema");
+const createSchema_1 = require("../markdown/createSchema");
 const primitives = {
     string: {
         default: () => "string",
@@ -51,7 +51,7 @@ function sampleResponseFromProp(name, prop, obj) {
         obj[name] = (0, exports.sampleResponseFromSchema)(prop.anyOf[0]);
     }
     else if (prop.allOf) {
-        const { mergedSchemas } = (0, createResponseSchema_1.mergeAllOf)(prop.allOf);
+        const { mergedSchemas } = (0, createSchema_1.mergeAllOf)(prop.allOf);
         sampleResponseFromProp(name, mergedSchemas, obj);
     }
     else {
@@ -68,7 +68,7 @@ const sampleResponseFromSchema = (schema = {}) => {
             return example;
         }
         if (allOf) {
-            const { mergedSchemas } = (0, createResponseSchema_1.mergeAllOf)(allOf);
+            const { mergedSchemas } = (0, createSchema_1.mergeAllOf)(allOf);
             if (mergedSchemas.properties) {
                 for (const [key, value] of Object.entries(mergedSchemas.properties)) {
                     if ((value.writeOnly && value.writeOnly === true) ||

package/lib/openapi/openapi.js

@@ -112,6 +112,13 @@ function createItems(openapiData, options, sidebarOptions) {
             const baseId = operationObject.operationId
                 ? (0, kebabCase_1.default)(operationObject.operationId)
                 : (0, kebabCase_1.default)(operationObject.summary);
+            const extensions = [];
+            const commonExtensions = ["x-codeSamples"];
+            for (const [key, value] of Object.entries(operationObject)) {
+                if (key.startsWith("x-") && !commonExtensions.includes(key)) {
+                    extensions.push({ key, value });
+                }
+            }
             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.
@@ -176,9 +183,13 @@ function createItems(openapiData, options, sidebarOptions) {
                     ...((options === null || options === void 0 ? void 0 : options.hideSendButton) && {
                         hide_send_button: options.hideSendButton,
                     }),
+                    ...((options === null || options === void 0 ? void 0 : options.showExtensions) && {
+                        show_extensions: options.showExtensions,
+                    }),
                 },
                 api: {
                     ...defaults,
+                    ...(extensions.length > 0 && { extensions: extensions }),
                     tags: operationObject.tags,
                     method,
                     path,
@@ -206,6 +217,13 @@ function createItems(openapiData, options, sidebarOptions) {
             const baseId = operationObject.operationId
                 ? (0, kebabCase_1.default)(operationObject.operationId)
                 : (0, kebabCase_1.default)(operationObject.summary);
+            const extensions = [];
+            const commonExtensions = ["x-codeSamples"];
+            for (const [key, value] of Object.entries(operationObject)) {
+                if (key.startsWith("x-") && !commonExtensions.includes(key)) {
+                    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;
             // Add security schemes so we know how to handle security.
@@ -270,9 +288,13 @@ function createItems(openapiData, options, sidebarOptions) {
                     ...((options === null || options === void 0 ? void 0 : options.hideSendButton) && {
                         hide_send_button: options.hideSendButton,
                     }),
+                    ...((options === null || options === void 0 ? void 0 : options.showExtensions) && {
+                        show_extensions: options.showExtensions,
+                    }),
                 },
                 api: {
                     ...defaults,
+                    ...(extensions.length > 0 && { extensions: extensions }),
                     tags: operationObject.tags,
                     method,
                     path,

package/lib/openapi/utils/loadAndResolveSpec.js

@@ -74,7 +74,6 @@ function convertSwagger2OpenAPI(spec) {
 }
 exports.convertSwagger2OpenAPI = convertSwagger2OpenAPI;
 async function resolveJsonRefs(specUrlOrObject) {
-    var _a, _b;
     try {
         let schema = await json_schema_ref_parser_1.default.dereference(specUrlOrObject, {
             continueOnError: true,
@@ -92,7 +91,15 @@ async function resolveJsonRefs(specUrlOrObject) {
         return schema;
     }
     catch (err) {
-        console.error(chalk_1.default.yellow((_b = (_a = err.errors[0]) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : err));
+        let errorMsg = "";
+        if (err.errors[0] !== undefined) {
+            const error = err.errors[0];
+            errorMsg = `Error: [${error.message}] with footprint [${error.footprint}]`;
+        }
+        else {
+            errorMsg = err;
+        }
+        console.error(chalk_1.default.yellow(errorMsg));
         return;
     }
 }

package/lib/options.js

@@ -26,6 +26,7 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         template: utils_validation_1.Joi.string(),
         downloadUrl: utils_validation_1.Joi.string(),
         hideSendButton: utils_validation_1.Joi.boolean(),
+        showExtensions: utils_validation_1.Joi.boolean(),
         sidebarOptions: sidebarOptions,
         version: utils_validation_1.Joi.string().when("versions", {
             is: utils_validation_1.Joi.exist(),

package/lib/types.d.ts

@@ -14,6 +14,7 @@ export interface APIOptions {
     template?: string;
     downloadUrl?: string;
     hideSendButton?: boolean;
+    showExtensions?: boolean;
     sidebarOptions?: SidebarOptions;
     version?: string;
     label?: string;
@@ -78,6 +79,7 @@ export interface ApiItem extends OperationObject {
     postman?: Request;
     proxy?: string;
     info: InfoObject;
+    extensions?: object;
 }
 export interface InfoPageMetadata extends ApiMetadataBase {
     type: "info";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.4",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,38 +28,30 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^2.3.0",
-    "@docusaurus/types": "^2.3.0",
+    "@docusaurus/types": ">=2.3.0 <2.5.0",
     "@types/fs-extra": "^9.0.13",
-    "@types/js-yaml": "^4.0.5",
     "@types/json-pointer": "^1.0.31",
     "@types/json-schema": "^7.0.9",
     "@types/lodash": "^4.14.176",
-    "@types/mustache": "^4.1.2",
-    "utility-types": "^3.10.0"
+    "@types/mustache": "^4.1.2"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^9.0.9",
-    "@docusaurus/mdx-loader": "^2.3.0",
-    "@docusaurus/plugin-content-docs": "^2.3.0",
-    "@docusaurus/utils": "^2.3.0",
-    "@docusaurus/utils-validation": "^2.3.0",
+    "@apidevtools/json-schema-ref-parser": "^10.1.0",
+    "@docusaurus/plugin-content-docs": ">=2.3.0 <2.5.0",
+    "@docusaurus/utils": ">=2.3.0 <2.5.0",
+    "@docusaurus/utils-validation": ">=2.3.0 <2.5.0",
     "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
     "@paloaltonetworks/postman-collection": "^4.1.0",
-    "@redocly/openapi-core": "^1.0.0-beta.103",
+    "@redocly/openapi-core": "^1.0.0-beta.125",
     "chalk": "^4.1.2",
     "clsx": "^1.1.1",
     "fs-extra": "^9.0.1",
-    "js-yaml": "^4.1.0",
     "json-pointer": "^0.6.2",
-    "json-refs": "^3.0.15",
     "json-schema-merge-allof": "^0.8.1",
     "lodash": "^4.17.20",
     "mustache": "^4.2.0",
     "slugify": "^1.6.5",
     "swagger2openapi": "^7.0.8",
-    "url-template": "^3.0.0",
-    "webpack": "^5.61.0",
     "xml-formatter": "^2.6.1"
   },
   "peerDependencies": {
@@ -68,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "ba8fd77e6b9e90e0bca5e169fbc1c71ac50f44e0"
+  "gitHead": "d7c1319c7977c3e7c54827b3950e5c9b66106e30"
 }

package/src/index.ts

@@ -7,6 +7,7 @@
 
 import fs from "fs";
 import path from "path";
+import zlib from "zlib";
 
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import { Globby, posixPath } from "@docusaurus/utils";
@@ -193,6 +194,9 @@ proxy: {{{frontMatter.proxy}}}
 {{#frontMatter.hide_send_button}}
 hide_send_button: true
 {{/frontMatter.hide_send_button}}
+{{#frontMatter.show_extensions}}
+show_extensions: true
+{{/frontMatter.show_extensions}}
 ---
 
 {{{markdown}}}
@@ -240,15 +244,17 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             item.downloadUrl = downloadUrl;
           }
         }
-        const markdown =
-          item.type === "api"
-            ? createApiPageMD(item)
-            : item.type === "info"
-            ? createInfoPageMD(item)
-            : createTagPageMD(item);
-        item.markdown = markdown;
         if (item.type === "api") {
-          item.json = JSON.stringify(item.api);
+          // opportunity to compress JSON
+          // const serialize = (o: any) => {
+          //   return zlib.deflateSync(JSON.stringify(o)).toString("base64");
+          // };
+          // const deserialize = (s: any) => {
+          //   return zlib.inflateSync(Buffer.from(s, "base64")).toString();
+          // };
+          item.json = zlib
+            .deflateSync(JSON.stringify(item.api))
+            .toString("base64");
           let infoBasePath = `${outputDir}/${item.infoId}`;
           if (docRouteBasePath) {
             infoBasePath = `${docRouteBasePath}/${outputDir
@@ -257,6 +263,13 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
           }
           if (item.infoId) item.infoPath = infoBasePath;
         }
+        const markdown =
+          item.type === "api"
+            ? createApiPageMD(item)
+            : item.type === "info"
+            ? createInfoPageMD(item)
+            : createTagPageMD(item);
+        item.markdown = markdown;
 
         const view = render(mdTemplate, item);
         const utils = render(infoMdTemplate, item);

package/src/markdown/createAuthorization.ts

@@ -0,0 +1,13 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { create } from "./utils";
+
+export function createAuthorization(infoPath: string) {
+  if (!infoPath) return undefined;
+  return [create("SecuritySchemes", { infoPath: infoPath }), "\n\n"];
+}

package/src/markdown/createParamsDetails.ts

@@ -32,7 +32,8 @@ export function createParamsDetails({ parameters, type }: Props) {
     children: [
       createDetailsSummary({
         children: [
-          create("strong", {
+          create("h3", {
+            className: "openapi-markdown__details-summary-header-params",
             children: `${
               type.charAt(0).toUpperCase() + type.slice(1)
             } Parameters`,

package/src/markdown/createRequestHeader.ts

@@ -0,0 +1,10 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+export function createRequestHeader(header: string) {
+  return `## ${header}\n\n`;
+}