docusaurus-plugin-openapi-docs 0.0.0-beta.638 → 0.0.0-beta.640

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}}}
@@ -196,12 +199,6 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                         item.downloadUrl = downloadUrl;
                     }
                 }
-                const markdown = item.type === "api"
-                    ? (0, markdown_1.createApiPageMD)(item)
-                    : item.type === "info"
-                        ? (0, markdown_1.createInfoPageMD)(item)
-                        : (0, markdown_1.createTagPageMD)(item);
-                item.markdown = markdown;
                 if (item.type === "api") {
                     item.json = JSON.stringify(item.api);
                     let infoBasePath = `${outputDir}/${item.infoId}`;
@@ -213,6 +210,12 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                     if (item.infoId)
                         item.infoPath = infoBasePath;
                 }
+                const markdown = item.type === "api"
+                    ? (0, markdown_1.createApiPageMD)(item)
+                    : item.type === "info"
+                        ? (0, markdown_1.createInfoPageMD)(item)
+                        : (0, markdown_1.createTagPageMD)(item);
+                item.markdown = markdown;
                 const view = (0, mustache_1.render)(mdTemplate, item);
                 const utils = (0, mustache_1.render)(infoMdTemplate, item);
                 // eslint-disable-next-line testing-library/render-result-naming-convention

package/lib/markdown/createAuthorization.d.ts

@@ -0,0 +1 @@
+export declare function createAuthorization(infoPath: string): string[] | undefined;

package/lib/markdown/createAuthorization.js

@@ -0,0 +1,16 @@
+"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.createAuthorization = void 0;
+const utils_1 = require("./utils");
+function createAuthorization(infoPath) {
+    if (!infoPath)
+        return undefined;
+    return [(0, utils_1.create)("SecuritySchemes", { infoPath: infoPath }), "\n\n"];
+}
+exports.createAuthorization = createAuthorization;

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, 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");
@@ -20,13 +21,15 @@ 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, 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 SecuritySchemes from "@theme/ApiDemoPanel/SecuritySchemes";\n`,
         `import MimeTabs from "@theme/MimeTabs";\n`,
         `import ParamsItem from "@theme/ParamsItem";\n`,
         `import ResponseSamples from "@theme/ResponseSamples";\n`,
@@ -35,6 +38,9 @@ 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),
+        `## ${title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")}\n\n`,
+        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, 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

@@ -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": "0.0.0-beta.638",
+  "version": "0.0.0-beta.640",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "9542413e1a3fdfef18eea605ce80799f5fc10686"
+  "gitHead": "78bb9c3cb5278a19b341dda5fb3fdab5b1901ecc"
 }

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}}}
@@ -240,13 +243,6 @@ 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);
           let infoBasePath = `${outputDir}/${item.infoId}`;
@@ -257,6 +253,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/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

@@ -13,6 +13,7 @@ import {
 } from "../openapi/types";
 import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
 import { createAuthentication } from "./createAuthentication";
+import { createAuthorization } from "./createAuthorization";
 import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
@@ -25,6 +26,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";
 
@@ -47,15 +49,19 @@ export function createApiPageMD({
     description,
     method,
     path,
+    extensions,
     parameters,
     requestBody,
     responses,
   },
+  infoPath,
+  frontMatter,
 }: ApiPageMetadata) {
   return render([
     `import ApiTabs from "@theme/ApiTabs";\n`,
     `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import MethodEndpoint from "@theme/ApiDemoPanel/MethodEndpoint";\n`,
+    `import SecuritySchemes from "@theme/ApiDemoPanel/SecuritySchemes";\n`,
     `import MimeTabs from "@theme/MimeTabs";\n`,
     `import ParamsItem from "@theme/ParamsItem";\n`,
     `import ResponseSamples from "@theme/ResponseSamples";\n`,
@@ -64,6 +70,9 @@ export function createApiPageMD({
     `import TabItem from "@theme/TabItem";\n\n`,
     createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
     createMethodEndpoint(method, path),
+    `## ${title.replace(lessThan, "<").replace(greaterThan, ">")}\n\n`,
+    infoPath && createAuthorization(infoPath),
+    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

@@ -28,6 +28,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;
@@ -105,6 +106,7 @@ export interface ApiItem extends OperationObject {
   postman?: Request;
   proxy?: string;
   info: InfoObject;
+  extensions?: object;
 }
 
 export interface InfoPageMetadata extends ApiMetadataBase {