docusaurus-plugin-openapi-docs 1.1.2 → 1.1.3

package/lib/openapi/openapi.js

@@ -16,7 +16,8 @@ const openapi_to_postmanv2_1 = __importDefault(require("@paloaltonetworks/openap
 const postman_collection_1 = __importDefault(require("@paloaltonetworks/postman-collection"));
 const chalk_1 = __importDefault(require("chalk"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const lodash_1 = require("lodash");
+const cloneDeep_1 = __importDefault(require("lodash/cloneDeep"));
+const kebabCase_1 = __importDefault(require("lodash/kebabCase"));
 const index_1 = require("../index");
 const createExample_1 = require("./createExample");
 const loadAndResolveSpec_1 = require("./utils/loadAndResolveSpec");
@@ -41,7 +42,7 @@ function jsonToCollection(data) {
 async function createPostmanCollection(openapiData) {
     var _a, _b, _c, _d, _e, _f, _g, _h;
     // Create copy of openapiData
-    const data = Object.assign({}, openapiData);
+    const data = (0, cloneDeep_1.default)(openapiData);
     // Including `servers` breaks postman, so delete all of them.
     delete data.servers;
     for (let pathItemObject of Object.values(data.paths)) {
@@ -61,7 +62,7 @@ function createItems(openapiData, sidebarOptions) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
     // TODO: Find a better way to handle this
     let items = [];
-    const infoId = (0, lodash_1.kebabCase)(openapiData.info.title);
+    const infoId = (0, kebabCase_1.default)(openapiData.info.title);
     if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
         // Only create an tag pages if categoryLinkSource set to tag.
         const tags = (_a = openapiData.tags) !== null && _a !== void 0 ? _a : [];
@@ -72,14 +73,13 @@ function createItems(openapiData, sidebarOptions) {
             .map((tag) => {
             var _a;
             const description = getTagDisplayName(tag.name, (_a = openapiData.tags) !== null && _a !== void 0 ? _a : []);
-            const tagId = (0, lodash_1.kebabCase)(tag.name);
+            const tagId = (0, kebabCase_1.default)(tag.name);
             const tagPage = {
                 type: "tag",
                 id: tagId,
                 unversionedId: tagId,
                 title: description !== null && description !== void 0 ? description : "",
                 description: description !== null && description !== void 0 ? description : "",
-                slug: "/" + tagId,
                 frontMatter: {},
                 tag: {
                     ...tag,
@@ -96,13 +96,14 @@ function createItems(openapiData, sidebarOptions) {
             unversionedId: infoId,
             title: openapiData.info.title,
             description: openapiData.info.description,
-            slug: "/" + infoId,
             frontMatter: {},
             securitySchemes: (_b = openapiData.components) === null || _b === void 0 ? void 0 : _b.securitySchemes,
             info: {
                 ...openapiData.info,
                 tags: (_c = openapiData.tags) === null || _c === void 0 ? void 0 : _c.map((tagName) => { var _a; return getTagDisplayName(tagName.name, (_a = openapiData.tags) !== null && _a !== void 0 ? _a : []); }),
                 title: (_d = openapiData.info.title) !== null && _d !== void 0 ? _d : "Introduction",
+                logo: openapiData.info["x-logo"],
+                darkLogo: openapiData.info["x-dark-logo"],
             },
         };
         items.push(infoPage);
@@ -116,8 +117,8 @@ function createItems(openapiData, sidebarOptions) {
                     (_h = (_g = operationObject.summary) !== null && _g !== void 0 ? _g : operationObject.operationId) !== null && _h !== void 0 ? _h : "";
             }
             const baseId = operationObject.operationId
-                ? (0, lodash_1.kebabCase)(operationObject.operationId)
-                : (0, lodash_1.kebabCase)(operationObject.summary);
+                ? (0, kebabCase_1.default)(operationObject.operationId)
+                : (0, kebabCase_1.default)(operationObject.summary);
             const servers = (_k = (_j = operationObject.servers) !== null && _j !== void 0 ? _j : pathObject.servers) !== null && _k !== void 0 ? _k : openapiData.servers;
             const security = (_l = operationObject.security) !== null && _l !== void 0 ? _l : openapiData.security;
             // Add security schemes so we know how to handle security.
@@ -144,7 +145,6 @@ function createItems(openapiData, sidebarOptions) {
                 unversionedId: baseId,
                 title: title,
                 description: description !== null && description !== void 0 ? description : "",
-                slug: "/" + baseId,
                 frontMatter: {},
                 api: {
                     ...defaults,

package/lib/openapi/types.d.ts

@@ -31,6 +31,13 @@ export interface InfoObject {
     license?: LicenseObject;
     version: string;
     tags?: String[];
+    "x-logo"?: LogoObject;
+    "x-dark-logo"?: LogoObject;
+    logo?: LogoObject;
+    darkLogo?: LogoObject;
+}
+export interface LogoObject {
+    url?: string;
 }
 export interface ContactObject {
     name?: string;

package/lib/openapi/utils/loadAndResolveSpec.js

@@ -15,6 +15,7 @@ const openapi_core_1 = require("@redocly/openapi-core");
 const chalk_1 = __importDefault(require("chalk"));
 // @ts-ignore
 const swagger2openapi_1 = require("swagger2openapi");
+const OpenAPIParser_1 = require("./services/OpenAPIParser");
 function serializer(replacer, cycleReplacer) {
     var stack = [], keys = [];
     if (cycleReplacer === undefined)
@@ -24,6 +25,18 @@ function serializer(replacer, cycleReplacer) {
             return value.title ? `circular(${value.title})` : "circular()";
         };
     return function (key, value) {
+        // Resolve discriminator ref pointers
+        if ((value === null || value === void 0 ? void 0 : value.discriminator) !== undefined) {
+            const parser = new OpenAPIParser_1.OpenAPIParser(stack[0]);
+            for (let [k, v] of Object.entries(value.discriminator.mapping)) {
+                const discriminator = k;
+                if (typeof v === "string" && v.charAt(0) === "#") {
+                    const ref = v;
+                    const resolvedRef = parser.byRef(ref);
+                    value.discriminator.mapping[discriminator] = resolvedRef;
+                }
+            }
+        }
         if (stack.length > 0) {
             // @ts-ignore
             var thisPos = stack.indexOf(this);

package/lib/sidebars/index.js

@@ -9,6 +9,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
 const clsx_1 = __importDefault(require("clsx"));
 const lodash_1 = require("lodash");
 const uniq_1 = __importDefault(require("lodash/uniq"));
@@ -98,8 +99,8 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
                 type: "generated-index",
                 title: tag,
                 slug: label
-                    ? "/category/" + (0, lodash_1.kebabCase)(label) + "/" + (0, lodash_1.kebabCase)(tag)
-                    : "/category/" + (0, lodash_1.kebabCase)(tag),
+                    ? path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(label), (0, lodash_1.kebabCase)(tag))
+                    : path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(tag)),
             };
         }
         return {

package/lib/types.d.ts

@@ -51,7 +51,7 @@ export interface ApiMetadataBase {
     description: string;
     source: string;
     sourceDirName: string;
-    slug: string;
+    slug?: string;
     permalink: string;
     sidebarPosition?: number;
     frontMatter: Record<string, unknown>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,8 +28,8 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-rc.1",
-    "@docusaurus/types": "2.0.0-rc.1",
+    "@docusaurus/module-type-aliases": "2.0.1",
+    "@docusaurus/types": "2.0.1",
     "@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.0-rc.1",
-    "@docusaurus/plugin-content-docs": "2.0.0-rc.1",
-    "@docusaurus/utils": "2.0.0-rc.1",
-    "@docusaurus/utils-validation": "2.0.0-rc.1",
+    "@docusaurus/mdx-loader": "2.0.1",
+    "@docusaurus/plugin-content-docs": "2.0.1",
+    "@docusaurus/utils": "2.0.1",
+    "@docusaurus/utils-validation": "2.0.1",
     "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
     "@paloaltonetworks/postman-collection": "^4.1.0",
     "@redocly/openapi-core": "^1.0.0-beta.103",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "0c66efff6ff553647265abdc27d4ca847c6d8045"
+  "gitHead": "4897267289b035aed8155f6001e14c80ba9003a8"
 }

package/src/markdown/createLogo.ts

@@ -0,0 +1,21 @@
+/* ============================================================================
+ * 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 { LogoObject } from "../openapi/types";
+import { create, guard } from "./utils";
+
+export function createLogo(
+  logo: LogoObject | undefined,
+  darkLogo: LogoObject | undefined
+) {
+  return guard(logo || darkLogo, () => [
+    create("ApiLogo", {
+      logo: logo,
+      darkLogo: darkLogo,
+    }),
+  ]);
+}

package/src/markdown/createSchemaDetails.ts

@@ -99,6 +99,7 @@ function createAnyOneOf(schema: SchemaObject): any {
 }
 
 function createProperties(schema: SchemaObject) {
+  const discriminator = schema.discriminator;
   return Object.entries(schema.properties!).map(([key, val]) =>
     createEdges({
       name: key,
@@ -106,6 +107,7 @@ function createProperties(schema: SchemaObject) {
       required: Array.isArray(schema.required)
         ? schema.required.includes(key)
         : false,
+      discriminator,
     })
   );
 }
@@ -277,6 +279,110 @@ function createItems(schema: SchemaObject) {
   );
 }
 
+/**
+ * For handling discriminators that do not map to a same-level property
+ */
+function createDiscriminator(schema: SchemaObject) {
+  const discriminator = schema.discriminator;
+  const propertyName = discriminator?.propertyName;
+  const propertyType = "string"; // should always be string
+  const mapping: any = discriminator?.mapping;
+
+  // Explicit mapping is required since we can't support implicit
+  if (mapping === undefined) {
+    return undefined;
+  }
+
+  // Attempt to get the property description we want to display
+  // TODO: how to make it predictable when handling allOf
+  let propertyDescription;
+  const firstMappingSchema = mapping[Object.keys(mapping)[0]];
+  if (firstMappingSchema.properties !== undefined) {
+    propertyDescription =
+      firstMappingSchema.properties![propertyName!].description;
+  }
+  if (firstMappingSchema.allOf !== undefined) {
+    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
+      firstMappingSchema.allOf
+    );
+    if (mergedSchemas.properties !== undefined) {
+      propertyDescription =
+        mergedSchemas.properties[propertyName!]?.description;
+    }
+  }
+
+  if (propertyDescription === undefined) {
+    if (
+      schema.properties !== undefined &&
+      schema.properties![propertyName!] !== undefined
+    ) {
+      propertyDescription = schema.properties![propertyName!].description;
+    }
+  }
+
+  return create("div", {
+    className: "discriminatorItem",
+    children: create("div", {
+      children: [
+        create("strong", {
+          style: { paddingLeft: "1rem" },
+          children: propertyName,
+        }),
+        guard(propertyType, (name) =>
+          create("span", {
+            style: { opacity: "0.6" },
+            children: ` ${propertyType}`,
+          })
+        ),
+        guard(getQualifierMessage(schema.discriminator as any), (message) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+        guard(propertyDescription, (description) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(description),
+          })
+        ),
+        create("DiscriminatorTabs", {
+          children: Object.keys(mapping!).map((key, index) => {
+            if (mapping[key].allOf !== undefined) {
+              const { mergedSchemas }: { mergedSchemas: SchemaObject } =
+                mergeAllOf(mapping[key].allOf);
+              // Cleanup duplicate property from mapping schema
+              delete mergedSchemas.properties![propertyName!];
+              mapping[key] = mergedSchemas;
+            }
+
+            if (mapping[key].properties !== undefined) {
+              // Cleanup duplicate property from mapping schema
+              delete mapping[key].properties![propertyName!];
+            }
+
+            const label = key;
+            return create("TabItem", {
+              label: label,
+              value: `${index}-item-discriminator`,
+              children: [
+                create("div", {
+                  style: { marginLeft: "-4px" },
+                  children: createNodes(mapping[key]),
+                }),
+              ],
+            });
+          }),
+        }),
+      ],
+    }),
+  });
+}
+
 function createDetailsNode(
   name: string,
   schemaName: string,
@@ -331,18 +437,109 @@ function createDetailsNode(
   });
 }
 
+/**
+ * For handling discriminators that map to a same-level property (like 'petType').
+ * Note: These should only be encountered while iterating through properties.
+ */
+function createPropertyDiscriminator(
+  name: string,
+  schemaName: string,
+  schema: SchemaObject,
+  discriminator: any,
+  required: any
+): any {
+  if (schema === undefined) {
+    return undefined;
+  }
+
+  if (discriminator.mapping === undefined) {
+    return undefined;
+  }
+
+  return create("div", {
+    className: "discriminatorItem",
+    children: create("div", {
+      children: [
+        create("strong", { style: { paddingLeft: "1rem" }, children: name }),
+        guard(schemaName, (name) =>
+          create("span", {
+            style: { opacity: "0.6" },
+            children: ` ${schemaName}`,
+          })
+        ),
+        guard(required, () => [
+          create("strong", {
+            style: {
+              fontSize: "var(--ifm-code-font-size)",
+              color: "var(--openapi-required)",
+            },
+            children: " required",
+          }),
+        ]),
+        guard(getQualifierMessage(discriminator), (message) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+        guard(schema.description, (description) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(description),
+          })
+        ),
+        create("DiscriminatorTabs", {
+          children: Object.keys(discriminator?.mapping!).map((key, index) => {
+            const label = key;
+            return create("TabItem", {
+              label: label,
+              value: `${index}-item-discriminator`,
+              children: [
+                create("div", {
+                  style: { marginLeft: "-4px" },
+                  children: createNodes(discriminator?.mapping[key]),
+                }),
+              ],
+            });
+          }),
+        }),
+      ],
+    }),
+  });
+}
+
 interface EdgeProps {
   name: string;
   schema: SchemaObject;
   required: boolean;
+  discriminator?: any | unknown;
 }
 
 /**
  * Creates the edges or "leaves" of a schema tree. Edges can branch into sub-nodes with createDetails().
  */
-function createEdges({ name, schema, required }: EdgeProps): any {
+function createEdges({
+  name,
+  schema,
+  required,
+  discriminator,
+}: EdgeProps): any {
   const schemaName = getSchemaName(schema);
 
+  if (discriminator !== undefined && discriminator.propertyName === name) {
+    return createPropertyDiscriminator(
+      name,
+      "string",
+      schema,
+      discriminator,
+      required
+    );
+  }
+
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
     return createDetailsNode(name, schemaName, schema, required);
   }
@@ -409,6 +606,10 @@ function createEdges({ name, schema, required }: EdgeProps): any {
  * Creates a hierarchical level of a schema tree. Nodes produce edges that can branch into sub-nodes with edges, recursively.
  */
 function createNodes(schema: SchemaObject): any {
+  if (schema.discriminator !== undefined) {
+    return createDiscriminator(schema);
+  }
+
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
     return createAnyOneOf(schema);
   }

package/src/markdown/createStatusCodes.ts

@@ -7,13 +7,86 @@
 
 import { ApiItem } from "../types";
 import { createDescription } from "./createDescription";
+import { createDetails } from "./createDetails";
+import { createDetailsSummary } from "./createDetailsSummary";
 import { createSchemaDetails } from "./createSchemaDetails";
 import { create } from "./utils";
+import { guard } from "./utils";
 
 interface Props {
   responses: ApiItem["responses"];
 }
 
+function createResponseHeaders(responseHeaders: any) {
+  return guard(responseHeaders, () =>
+    create("ul", {
+      style: { marginLeft: "1rem" },
+      children: [
+        Object.entries(responseHeaders).map(([headerName, headerObj]) => {
+          const {
+            description,
+            schema: { type },
+            example,
+          }: any = headerObj;
+
+          return create("li", {
+            class: "schemaItem",
+            children: [
+              createDetailsSummary({
+                children: [
+                  create("strong", { children: headerName }),
+                  guard(type, () => [
+                    create("span", {
+                      style: { opacity: "0.6" },
+                      children: ` ${type}`,
+                    }),
+                  ]),
+                ],
+              }),
+              create("div", {
+                children: [
+                  guard(description, (description) =>
+                    create("div", {
+                      style: {
+                        marginTop: ".5rem",
+                        marginBottom: ".5rem",
+                      },
+                      children: [
+                        guard(example, () => `Example: ${example}`),
+                        createDescription(description),
+                      ],
+                    })
+                  ),
+                ],
+              }),
+            ],
+          });
+        }),
+      ],
+    })
+  );
+}
+
+function createResponseExamples(responseExamples: any) {
+  return Object.entries(responseExamples).map(
+    ([exampleName, exampleValue]: any) => {
+      const camelToSpaceName = exampleName.replace(/([A-Z])/g, " $1");
+      let finalFormattedName =
+        camelToSpaceName.charAt(0).toUpperCase() + camelToSpaceName.slice(1);
+
+      return create("TabItem", {
+        label: `${finalFormattedName}`,
+        value: `${finalFormattedName}`,
+        children: [
+          create("ResponseSamples", {
+            responseExample: JSON.stringify(exampleValue.value, null, 2),
+          }),
+        ],
+      });
+    }
+  );
+}
+
 export function createStatusCodes({ responses }: Props) {
   if (responses === undefined) {
     return undefined;
@@ -28,6 +101,13 @@ export function createStatusCodes({ responses }: Props) {
     children: [
       create("ApiTabs", {
         children: codes.map((code) => {
+          const responseHeaders: any = responses[code].headers;
+          const responseContent: any = responses[code].content;
+          const responseContentKey: any =
+            responseContent && Object.keys(responseContent)[0];
+          const responseExamples: any =
+            responseContentKey && responseContent[responseContentKey].examples;
+
           return create("TabItem", {
             label: code,
             value: code,
@@ -35,14 +115,68 @@ export function createStatusCodes({ responses }: Props) {
               create("div", {
                 children: createDescription(responses[code].description),
               }),
-              create("div", {
-                children: createSchemaDetails({
-                  title: "Schema",
-                  body: {
-                    content: responses[code].content,
-                  },
-                }),
-              }),
+              guard(responseExamples, () =>
+                create("SchemaTabs", {
+                  children: [
+                    create("TabTtem", {
+                      label: "Schema",
+                      value: "Schema",
+                      children: [
+                        responseHeaders &&
+                          createDetails({
+                            "data-collaposed": false,
+                            open: true,
+                            style: { textAlign: "left" },
+                            children: [
+                              createDetailsSummary({
+                                children: [
+                                  create("strong", {
+                                    children: "Response Headers",
+                                  }),
+                                ],
+                              }),
+                              createResponseHeaders(responseHeaders),
+                            ],
+                          }),
+                        create("div", {
+                          children: createSchemaDetails({
+                            title: "Schema",
+                            body: {
+                              content: responses[code].content,
+                            },
+                          }),
+                        }),
+                      ],
+                    }),
+                    createResponseExamples(responseExamples),
+                  ],
+                })
+              ),
+              guard(responseHeaders, () =>
+                createDetails({
+                  "data-collaposed": false,
+                  open: true,
+                  style: { textAlign: "left" },
+                  children: [
+                    createDetailsSummary({
+                      children: [
+                        create("strong", { children: "Response Headers" }),
+                      ],
+                    }),
+                    createResponseHeaders(responseHeaders),
+                  ],
+                })
+              ),
+              guard(!responseExamples, () =>
+                create("div", {
+                  children: createSchemaDetails({
+                    title: "Schema",
+                    body: {
+                      content: responses[code].content,
+                    },
+                  }),
+                })
+              ),
             ],
           });
         }),

package/src/markdown/index.ts

@@ -18,6 +18,7 @@ import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
 import { createLicense } from "./createLicense";
+import { createLogo } from "./createLogo";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
@@ -37,10 +38,12 @@ export function createApiPageMD({
   },
 }: ApiPageMetadata) {
   return render([
+    `import ApiTabs from "@theme/ApiTabs";\n`,
     `import ParamsItem from "@theme/ParamsItem";\n`,
+    `import ResponseSamples from "@theme/ResponseSamples";\n`,
     `import SchemaItem from "@theme/SchemaItem"\n`,
-    `import ApiTabs from "@theme/ApiTabs";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     `## ${escape(title)}\n\n`,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
@@ -55,14 +58,26 @@ export function createApiPageMD({
 }
 
 export function createInfoPageMD({
-  info: { title, version, description, contact, license, termsOfService },
+  info: {
+    title,
+    version,
+    description,
+    contact,
+    license,
+    termsOfService,
+    logo,
+    darkLogo,
+  },
   securitySchemes,
 }: InfoPageMetadata) {
   return render([
+    `import ApiLogo from "@theme/ApiLogo";\n`,
     `import Tabs from "@theme/Tabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
+
     createVersionBadge(version),
     `# ${escape(title)}\n\n`,
+    createLogo(logo, darkLogo),
     createDescription(description),
     createAuthentication(securitySchemes as unknown as SecuritySchemeObject),
     createContactInfo(contact as ContactObject),