docusaurus-plugin-openapi-docs 1.7.0 → 1.7.2

package/README.md

@@ -125,6 +125,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `template`       | `string`  | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
 | `downloadUrl`    | `string`  | `null`  | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc)                             |
 | `hideSendButton` | `boolean` | `null`  | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel                                         |
+| `showExtensions` | `boolean` | `null`  | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description.                                     |
 | `sidebarOptions` | `object`  | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                            |
 | `version`        | `string`  | `null`  | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`.                                           |
 | `label`          | `string`  | `null`  | _Optional:_ Version label used when generating version selector dropdown menu.                                              |

package/lib/index.js

@@ -152,6 +152,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}}}

package/lib/markdown/createVendorExtensions.d.ts

@@ -0,0 +1 @@
+export declare function createVendorExtensions(extensions: any): string | undefined;

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, parameters, requestBody, responses, }, }: ApiPageMetadata): string;
+export declare function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, extensions, parameters, requestBody, responses, }, 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

@@ -18,9 +18,10 @@ const createParamsDetails_1 = require("./createParamsDetails");
 const createRequestBodyDetails_1 = require("./createRequestBodyDetails");
 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, parameters, requestBody, responses, }, }) {
+function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, extensions, parameters, requestBody, responses, }, frontMatter, }) {
     return (0, utils_1.render)([
         `import ApiTabs from "@theme/ApiTabs";\n`,
         `import MimeTabs from "@theme/MimeTabs";\n`,
@@ -31,6 +32,7 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
         `## ${title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")}\n\n`,
+        frontMatter.show_extensions && (0, createVendorExtensions_1.createVendorExtensions)(extensions),
         (0, createDeprecationNotice_1.createDeprecationNotice)({ deprecated, description: deprecatedDescription }),
         (0, createDescription_1.createDescription)(description),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "path" }),

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/options.js

@@ -27,6 +27,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;
@@ -76,6 +77,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": "1.7.0",
+  "version": "1.7.2",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -39,14 +39,14 @@
     "utility-types": "^3.10.0"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^9.0.9",
+    "@apidevtools/json-schema-ref-parser": "^10.1.0",
     "@docusaurus/mdx-loader": ">=2.0.1 <2.3.0",
     "@docusaurus/plugin-content-docs": ">=2.0.1 <2.3.0",
     "@docusaurus/utils": ">=2.0.1 <2.3.0",
     "@docusaurus/utils-validation": ">=2.0.1 <2.3.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",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "4b9ac927c85b56054c8d93336b1b5e282ab309e7"
+  "gitHead": "d6450052aff8a6fc691aef3d38bf835f4c70b1ef"
 }

package/src/index.ts

@@ -193,6 +193,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}}}

package/src/markdown/createVendorExtensions.ts

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

package/src/markdown/index.ts

@@ -23,6 +23,7 @@ import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
 import { createTermsOfService } from "./createTermsOfService";
+import { createVendorExtensions } from "./createVendorExtensions";
 import { createVersionBadge } from "./createVersionBadge";
 import { greaterThan, lessThan, render } from "./utils";
 
@@ -43,10 +44,12 @@ export function createApiPageMD({
     deprecated,
     "x-deprecated-description": deprecatedDescription,
     description,
+    extensions,
     parameters,
     requestBody,
     responses,
   },
+  frontMatter,
 }: ApiPageMetadata) {
   return render([
     `import ApiTabs from "@theme/ApiTabs";\n`,
@@ -58,6 +61,7 @@ export function createApiPageMD({
     `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     `## ${title.replace(lessThan, "<").replace(greaterThan, ">")}\n\n`,
+    frontMatter.show_extensions && createVendorExtensions(extensions),
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
     createDescription(description),
     createParamsDetails({ parameters, type: "path" }),

package/src/openapi/openapi.ts

@@ -144,6 +144,15 @@ function createItems(
         ? kebabCase(operationObject.operationId)
         : kebabCase(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 =
         operationObject.servers ?? pathObject.servers ?? openapiData.servers;
 
@@ -224,9 +233,13 @@ function createItems(
           ...(options?.hideSendButton && {
             hide_send_button: options.hideSendButton,
           }),
+          ...(options?.showExtensions && {
+            show_extensions: options.showExtensions,
+          }),
         },
         api: {
           ...defaults,
+          ...(extensions.length > 0 && { extensions: extensions }),
           tags: operationObject.tags,
           method,
           path,
@@ -264,6 +277,15 @@ function createItems(
         ? kebabCase(operationObject.operationId)
         : kebabCase(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 =
         operationObject.servers ?? pathObject.servers ?? openapiData.servers;
 
@@ -344,9 +366,13 @@ function createItems(
           ...(options?.hideSendButton && {
             hide_send_button: options.hideSendButton,
           }),
+          ...(options?.showExtensions && {
+            show_extensions: options.showExtensions,
+          }),
         },
         api: {
           ...defaults,
+          ...(extensions.length > 0 && { extensions: extensions }),
           tags: operationObject.tags,
           method,
           path,

package/src/options.ts

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

package/src/types.ts

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