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

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";
@@ -23,8 +24,10 @@ import { createLogo } from "./createLogo";
 import { createMethodEndpoint } from "./createMethodEndpoint";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
+import { createRequestHeader } from "./createRequestHeader";
 import { createStatusCodes } from "./createStatusCodes";
 import { createTermsOfService } from "./createTermsOfService";
+import { createVendorExtensions } from "./createVendorExtensions";
 import { createVersionBadge } from "./createVersionBadge";
 import { greaterThan, lessThan, render } from "./utils";
 
@@ -47,15 +50,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,14 +71,17 @@ export function createApiPageMD({
     `import TabItem from "@theme/TabItem";\n\n`,
     createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
     createMethodEndpoint(method, path),
+    infoPath && createAuthorization(infoPath),
+    frontMatter.show_extensions && createVendorExtensions(extensions),
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
     createDescription(description),
+    createRequestHeader("Request"),
     createParamsDetails({ parameters, type: "path" }),
     createParamsDetails({ parameters, type: "query" }),
     createParamsDetails({ parameters, type: "header" }),
     createParamsDetails({ parameters, type: "cookie" }),
     createRequestBodyDetails({
-      title: "Request Body",
+      title: "Body",
       body: requestBody,
     } as Props),
     createStatusCodes({ responses }),

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/openapi/utils/loadAndResolveSpec.ts

@@ -101,7 +101,16 @@ async function resolveJsonRefs(specUrlOrObject: object | string) {
     });
     return schema as OpenApiObject;
   } catch (err: any) {
-    console.error(chalk.yellow(err.errors[0]?.message ?? 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.yellow(errorMsg));
     return;
   }
 }

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 {