docusaurus-plugin-openapi-docs 1.5.2 → 1.6.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,8 +28,8 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^2.0.1",
-    "@docusaurus/types": "^2.0.1",
+    "@docusaurus/module-type-aliases": ">=2.0.1 <2.3.0",
+    "@docusaurus/types": ">=2.0.1 <2.3.0",
     "@types/fs-extra": "^9.0.13",
     "@types/js-yaml": "^4.0.5",
     "@types/json-pointer": "^1.0.31",
@@ -40,10 +40,10 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^9.0.9",
-    "@docusaurus/mdx-loader": "^2.0.1",
-    "@docusaurus/plugin-content-docs": "^2.0.1",
-    "@docusaurus/utils": "^2.0.1",
-    "@docusaurus/utils-validation": "^2.0.1",
+    "@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",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "fa3096190356c0161a8e255b9950857a7b131eef"
+  "gitHead": "68f648d80d41b82a607215bac0a082f931f80b7c"
 }

package/src/index.ts

@@ -94,6 +94,9 @@ export default function pluginOpenAPIDocs(
     let { specPath, outputDir, template, downloadUrl, sidebarOptions } =
       options;
 
+    // Remove trailing slash before proceeding
+    outputDir = outputDir.replace(/\/$/, "");
+
     // Override docPath if pluginId provided
     if (pluginId) {
       docData = getDocsPluginConfig(presetsPlugins, pluginId);
@@ -187,6 +190,9 @@ custom_edit_url: null
 {{#frontMatter.proxy}}
 proxy: {{{frontMatter.proxy}}}
 {{/frontMatter.proxy}}
+{{#frontMatter.hide_send_button}}
+hide_send_button: true
+{{/frontMatter.hide_send_button}}
 ---
 
 {{{markdown}}}

package/src/markdown/createAuthentication.ts

@@ -13,7 +13,8 @@ export function createAuthentication(securitySchemes: SecuritySchemeObject) {
   if (!securitySchemes || !Object.keys(securitySchemes).length) return "";
 
   const createAuthenticationTable = (securityScheme: any) => {
-    const { bearerFormat, flows, name, scheme, type } = securityScheme;
+    const { bearerFormat, flows, name, scheme, type, openIdConnectUrl } =
+      securityScheme;
 
     const createSecuritySchemeTypeRow = () =>
       create("tr", {
@@ -30,7 +31,7 @@ export function createAuthentication(securitySchemes: SecuritySchemeObject) {
 
         return create("tr", {
           children: [
-            create("th", { children: `${flowType} OAuth Flow:` }),
+            create("th", { children: `OAuth Flow (${flowType}):` }),
             create("td", {
               children: [
                 guard(tokenUrl, () =>
@@ -91,12 +92,14 @@ export function createAuthentication(securitySchemes: SecuritySchemeObject) {
                       create("td", { children: scheme }),
                     ],
                   }),
-                  create("tr", {
-                    children: [
-                      create("th", { children: "Bearer format:" }),
-                      create("td", { children: bearerFormat }),
-                    ],
-                  }),
+                  guard(bearerFormat, () =>
+                    create("tr", {
+                      children: [
+                        create("th", { children: "Bearer format:" }),
+                        create("td", { children: bearerFormat }),
+                      ],
+                    })
+                  ),
                 ],
               }),
             }),
@@ -115,23 +118,51 @@ export function createAuthentication(securitySchemes: SecuritySchemeObject) {
             }),
           ],
         });
+      case "openIdConnect":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  guard(openIdConnectUrl, () =>
+                    create("tr", {
+                      children: [
+                        create("th", { children: "OpenID Connect URL:" }),
+                        create("td", { children: openIdConnectUrl }),
+                      ],
+                    })
+                  ),
+                ],
+              }),
+            }),
+          ],
+        });
       default:
         return "";
     }
   };
 
-  const formatTabLabel = (str: string) => {
-    const formattedLabel = str
+  const formatTabLabel = (key: string, type: string, scheme: string) => {
+    const formattedLabel = key
       .replace(/(_|-)/g, " ")
       .trim()
       .replace(/\w\S*/g, (str) => str.charAt(0).toUpperCase() + str.substr(1))
       .replace(/([a-z])([A-Z])/g, "$1 $2")
       .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2");
+    const isOAuth = type === "oauth2";
+    const isApiKey = type === "apiKey";
+    const isHttpBasic = type === "http" && scheme === "basic";
+    const isHttpBearer = type === "http" && scheme === "bearer";
+    const isOpenId = type === "openIdConnect";
 
-    const isOAuth = formattedLabel.toLowerCase().includes("oauth2");
-    const isApiKey = formattedLabel.toLowerCase().includes("api");
+    if (isOAuth) return `OAuth 2.0: ${key}`;
+    if (isApiKey) return `API Key: ${key}`;
+    if (isHttpBasic) return "HTTP: Basic Auth";
+    if (isHttpBearer) return "HTTP: Bearer Auth";
+    if (isOpenId) return `OpenID Connect: ${key}`;
 
-    return isOAuth ? "OAuth 2.0" : isApiKey ? "API Key" : formattedLabel;
+    return formattedLabel;
   };
 
   return create("div", {
@@ -141,12 +172,17 @@ export function createAuthentication(securitySchemes: SecuritySchemeObject) {
         id: "authentication",
         style: { marginBottom: "1rem" },
       }),
-      create("Tabs", {
+      create("SchemaTabs", {
+        className: "openapi-tabs__security-schemes",
         children: Object.entries(securitySchemes).map(
-          ([schemeType, schemeObj]) =>
+          ([schemeKey, schemeObj]) =>
             create("TabItem", {
-              label: formatTabLabel(schemeType),
-              value: `${schemeType}`,
+              label: formatTabLabel(
+                schemeKey,
+                schemeObj.type,
+                schemeObj.scheme
+              ),
+              value: `${schemeKey}`,
               children: [
                 createDescription(schemeObj.description),
                 createAuthenticationTable(schemeObj),

package/src/markdown/createRequestSchema.ts

@@ -34,7 +34,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
         return true;
       },
     },
-    ignoreAdditionalProperties: true,
+    ignoreAdditionalProperties: false,
   });
 
   const required = allOf.reduce((acc, cur) => {
@@ -157,6 +157,28 @@ function createAdditionalProperties(schema: SchemaObject) {
   //   },
   //   type: 'array'
   // }
+  const additionalProperties = schema.additionalProperties;
+  const type: string | unknown = additionalProperties?.type;
+  if (
+    (type === "object" || type === "array") &&
+    (additionalProperties?.properties ||
+      additionalProperties?.items ||
+      additionalProperties?.allOf ||
+      additionalProperties?.additionalProperties ||
+      additionalProperties?.oneOf ||
+      additionalProperties?.anyOf)
+  ) {
+    const title = additionalProperties.title;
+    const schemaName = title ? `object (${title})` : "object";
+    const required = schema.required ?? false;
+    return createDetailsNode(
+      "property name*",
+      schemaName,
+      additionalProperties,
+      required,
+      schema.nullable
+    );
+  }
 
   if (
     (schema.additionalProperties?.type as string) === "string" ||
@@ -165,7 +187,6 @@ function createAdditionalProperties(schema: SchemaObject) {
     (schema.additionalProperties?.type as string) === "integer" ||
     (schema.additionalProperties?.type as string) === "number"
   ) {
-    const type = schema.additionalProperties?.type;
     const additionalProperties =
       schema.additionalProperties?.additionalProperties;
     if (additionalProperties !== undefined) {
@@ -436,7 +457,8 @@ function createDetailsNode(
   name: string,
   schemaName: string,
   schema: SchemaObject,
-  required: string[] | boolean
+  required: string[] | boolean,
+  nullable: boolean | unknown
 ): any {
   return create("SchemaItem", {
     collapsible: true,
@@ -451,15 +473,19 @@ function createDetailsNode(
                 style: { opacity: "0.6" },
                 children: ` ${schemaName}`,
               }),
-              guard(schema.nullable && schema.nullable === true, () => [
-                create("strong", {
-                  style: {
-                    fontSize: "var(--ifm-code-font-size)",
-                    color: "var(--openapi-nullable)",
-                  },
-                  children: " nullable",
-                }),
-              ]),
+              guard(
+                (schema.nullable && schema.nullable === true) ||
+                  (nullable && nullable === true),
+                () => [
+                  create("strong", {
+                    style: {
+                      fontSize: "var(--ifm-code-font-size)",
+                      color: "var(--openapi-nullable)",
+                    },
+                    children: " nullable",
+                  }),
+                ]
+              ),
               guard(
                 Array.isArray(required)
                   ? required.includes(name)
@@ -604,7 +630,13 @@ function createEdges({
   }
 
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.allOf !== undefined) {
@@ -619,20 +651,44 @@ function createEdges({
       mergedSchemas.oneOf !== undefined ||
       mergedSchemas.anyOf !== undefined
     ) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.properties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.additionalProperties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     // array of objects
     if (mergedSchemas.items?.properties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
@@ -650,20 +706,44 @@ function createEdges({
   }
 
   if (schema.properties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.additionalProperties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   // array of objects
   if (schema.items?.properties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.items?.anyOf !== undefined || schema.items?.oneOf !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.readOnly && schema.readOnly === true) {
@@ -751,7 +831,7 @@ function createNodes(schema: SchemaObject): any {
 
   // Unknown node/schema type should return undefined
   // So far, haven't seen this hit in testing
-  return undefined;
+  return "any";
 }
 
 interface Props {
@@ -840,7 +920,8 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
   }
 
   const randomFirstKey = Object.keys(body.content)[0];
-  const firstBody = body.content[randomFirstKey].schema;
+  const firstBody: any =
+    body.content[randomFirstKey].schema ?? body.content![randomFirstKey];
 
   if (firstBody === undefined) {
     return undefined;

package/src/markdown/createResponseSchema.ts

@@ -163,6 +163,28 @@ function createAdditionalProperties(schema: SchemaObject) {
   //   },
   //   type: 'array'
   // }
+  const additionalProperties = schema.additionalProperties;
+  const type: string | unknown = additionalProperties?.type;
+  if (
+    (type === "object" || type === "array") &&
+    (additionalProperties?.properties ||
+      additionalProperties?.items ||
+      additionalProperties?.allOf ||
+      additionalProperties?.additionalProperties ||
+      additionalProperties?.oneOf ||
+      additionalProperties?.anyOf)
+  ) {
+    const title = additionalProperties.title;
+    const schemaName = title ? `object (${title})` : "object";
+    const required = schema.required ?? false;
+    return createDetailsNode(
+      "property name*",
+      schemaName,
+      additionalProperties,
+      required,
+      schema.nullable
+    );
+  }
 
   if (
     (schema.additionalProperties?.type as string) === "string" ||
@@ -171,7 +193,6 @@ function createAdditionalProperties(schema: SchemaObject) {
     (schema.additionalProperties?.type as string) === "integer" ||
     (schema.additionalProperties?.type as string) === "number"
   ) {
-    const type = schema.additionalProperties?.type;
     const additionalProperties =
       schema.additionalProperties?.additionalProperties;
     if (additionalProperties !== undefined) {
@@ -442,7 +463,8 @@ function createDetailsNode(
   name: string,
   schemaName: string,
   schema: SchemaObject,
-  required: string[] | boolean
+  required: string[] | boolean,
+  nullable: boolean | unknown
 ): any {
   return create("SchemaItem", {
     collapsible: true,
@@ -457,24 +479,33 @@ function createDetailsNode(
                 style: { opacity: "0.6" },
                 children: ` ${schemaName}`,
               }),
-              guard(schema.nullable && schema.nullable === true, () => [
-                create("strong", {
-                  style: {
-                    fontSize: "var(--ifm-code-font-size)",
-                    color: "var(--openapi-nullable)",
-                  },
-                  children: " nullable",
-                }),
-              ]),
-              guard(schema.required && schema.required === true, () => [
-                create("strong", {
-                  style: {
-                    fontSize: "var(--ifm-code-font-size)",
-                    color: "var(--openapi-required)",
-                  },
-                  children: " required",
-                }),
-              ]),
+              guard(
+                (schema.nullable && schema.nullable === true) ||
+                  (nullable && nullable === true),
+                () => [
+                  create("strong", {
+                    style: {
+                      fontSize: "var(--ifm-code-font-size)",
+                      color: "var(--openapi-nullable)",
+                    },
+                    children: " nullable",
+                  }),
+                ]
+              ),
+              guard(
+                Array.isArray(required)
+                  ? required.includes(name)
+                  : required === true,
+                () => [
+                  create("strong", {
+                    style: {
+                      fontSize: "var(--ifm-code-font-size)",
+                      color: "var(--openapi-required)",
+                    },
+                    children: " required",
+                  }),
+                ]
+              ),
             ],
           }),
           create("div", {
@@ -605,7 +636,13 @@ function createEdges({
   }
 
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.allOf !== undefined) {
@@ -620,20 +657,44 @@ function createEdges({
       mergedSchemas.oneOf !== undefined ||
       mergedSchemas.anyOf !== undefined
     ) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.properties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.additionalProperties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     // array of objects
     if (mergedSchemas.items?.properties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
@@ -643,7 +704,7 @@ function createEdges({
     return create("SchemaItem", {
       collapsible: false,
       name,
-      required: false,
+      required: Array.isArray(required) ? required.includes(name) : required,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
       schema: mergedSchemas,
@@ -651,20 +712,44 @@ function createEdges({
   }
 
   if (schema.properties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.additionalProperties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   // array of objects
   if (schema.items?.properties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.items?.anyOf !== undefined || schema.items?.oneOf !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.writeOnly && schema.writeOnly === true) {
@@ -675,7 +760,7 @@ function createEdges({
   return create("SchemaItem", {
     collapsible: false,
     name,
-    required: false,
+    required: Array.isArray(required) ? required.includes(name) : required,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),
     schema: schema,
@@ -697,7 +782,6 @@ function createNodes(schema: SchemaObject): any {
 
   if (schema.allOf !== undefined) {
     const { mergedSchemas } = mergeAllOf(schema.allOf);
-
     if (mergedSchemas.properties !== undefined) {
       nodes.push(createProperties(mergedSchemas));
     }
@@ -755,7 +839,7 @@ function createNodes(schema: SchemaObject): any {
 
   // Unknown node/schema type should return undefined
   // So far, haven't seen this hit in testing
-  return undefined;
+  return "any";
 }
 
 interface Props {
@@ -789,7 +873,8 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
       children: mimeTypes.map((mimeType: any) => {
         const responseExamples = body.content![mimeType].examples;
         const responseExample = body.content![mimeType].example;
-        const firstBody = body.content![mimeType].schema;
+        const firstBody: any =
+          body.content![mimeType].schema ?? body.content![mimeType];
 
         if (
           firstBody === undefined &&