docusaurus-plugin-openapi-docs 1.1.0 → 1.1.3

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),

package/src/markdown/schema.test.ts

@@ -17,19 +17,19 @@ describe("getQualifierMessage", () => {
   // minLength + maxLength
   //
   it("should render minLength", () => {
-    const expected = "**Possible values:** 1 ≤ length";
+    const expected = "**Possible values:** `non-empty`";
     const actual = getQualifierMessage({ minLength: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render maxLength", () => {
-    const expected = "**Possible values:** length ≤ 40";
+    const expected = "**Possible values:** `<= 40 characters`";
     const actual = getQualifierMessage({ maxLength: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render minLength and maxLength", () => {
-    const expected = "**Possible values:** 1 ≤ length ≤ 40";
+    const expected = "**Possible values:** `non-empty` and `<= 40 characters`";
     const actual = getQualifierMessage({ minLength: 1, maxLength: 40 });
     expect(actual).toBe(expected);
   });
@@ -46,7 +46,7 @@ describe("getQualifierMessage", () => {
 
   it("should render multiple string qualifiers", () => {
     const expected =
-      "**Possible values:** 1 ≤ length ≤ 40, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
+      "**Possible values:** `non-empty` and `<= 40 characters`, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
     const actual = getQualifierMessage({
       minLength: 1,
       maxLength: 40,
@@ -68,49 +68,49 @@ describe("getQualifierMessage", () => {
   // minimum + maximum + exclusiveMinimum + exclusiveMaximum
   //
   it("should render minimum", () => {
-    const expected = "**Possible values:** 1 ≤ value";
+    const expected = "**Possible values:** `>= 1`";
     const actual = getQualifierMessage({ minimum: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render maximum", () => {
-    const expected = "**Possible values:** value ≤ 40";
+    const expected = "**Possible values:** `<= 40`";
     const actual = getQualifierMessage({ maximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render numeric exclusiveMinimum", () => {
-    const expected = "**Possible values:** 1 < value";
+    const expected = "**Possible values:** `> 1`";
     const actual = getQualifierMessage({ exclusiveMinimum: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render numeric exclusiveMaximum", () => {
-    const expected = "**Possible values:** value < 40";
+    const expected = "**Possible values:** `< 40`";
     const actual = getQualifierMessage({ exclusiveMaximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMinimum", () => {
-    const expected = "**Possible values:** 1 < value";
+    const expected = "**Possible values:** `> 1`";
     const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: true });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** value < 40";
+    const expected = "**Possible values:** `< 40`";
     const actual = getQualifierMessage({ maximum: 40, exclusiveMaximum: true });
     expect(actual).toBe(expected);
   });
 
   it("should render minimum when exclusiveMinimum is false", () => {
-    const expected = "**Possible values:** 1 ≤ value";
+    const expected = "**Possible values:** `>= 1`";
     const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: false });
     expect(actual).toBe(expected);
   });
 
   it("should render maximum when exclusiveMaximum is false", () => {
-    const expected = "**Possible values:** value ≤ 40";
+    const expected = "**Possible values:** `<= 40`";
     const actual = getQualifierMessage({
       maximum: 40,
       exclusiveMaximum: false,
@@ -119,13 +119,13 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and maximum", () => {
-    const expected = "**Possible values:** 1 ≤ value ≤ 40";
+    const expected = "**Possible values:** `>= 1` and `<= 40`";
     const actual = getQualifierMessage({ minimum: 1, maximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMinimum and maximum", () => {
-    const expected = "**Possible values:** 1 < value ≤ 40";
+    const expected = "**Possible values:** `> 1` and `<= 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       maximum: 40,
@@ -135,7 +135,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 ≤ value < 40";
+    const expected = "**Possible values:** `>= 1` and `< 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       maximum: 40,
@@ -145,7 +145,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render numeric exclusiveMinimum and maximum", () => {
-    const expected = "**Possible values:** 1 < value ≤ 40";
+    const expected = "**Possible values:** `> 1` and `<= 40`";
     const actual = getQualifierMessage({
       exclusiveMinimum: 1,
       maximum: 40,
@@ -154,7 +154,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and numeric exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 ≤ value < 40";
+    const expected = "**Possible values:** `>= 1` and `< 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       exclusiveMaximum: 40,
@@ -163,7 +163,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render numeric exclusiveMinimum and boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 < value < 40";
+    const expected = "**Possible values:** `> 1` and `< 40`";
     const actual = getQualifierMessage({
       exclusiveMinimum: 1,
       maximum: 40,

package/src/markdown/schema.ts

@@ -64,7 +64,11 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     return undefined;
   }
 
-  if (schema.items) {
+  if (
+    schema.items &&
+    schema.minItems === undefined &&
+    schema.maxItems === undefined
+  ) {
     return getQualifierMessage(schema.items);
   }
 
@@ -72,15 +76,38 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
 
   let qualifierGroups = [];
 
+  if (schema.items && schema.items.enum) {
+    if (schema.items.enum) {
+      qualifierGroups.push(
+        `[${schema.items.enum.map((e) => `\`${e}\``).join(", ")}]`
+      );
+    }
+  }
+
   if (schema.minLength || schema.maxLength) {
     let lengthQualifier = "";
-    if (schema.minLength) {
-      lengthQualifier += `${schema.minLength} ≤ `;
+    let minLength;
+    let maxLength;
+    if (schema.minLength && schema.minLength > 1) {
+      minLength = `\`>= ${schema.minLength} characters\``;
+    }
+    if (schema.minLength && schema.minLength === 1) {
+      minLength = `\`non-empty\``;
     }
-    lengthQualifier += "length";
     if (schema.maxLength) {
-      lengthQualifier += ` ≤ ${schema.maxLength}`;
+      maxLength = `\`<= ${schema.maxLength} characters\``;
+    }
+
+    if (minLength && !maxLength) {
+      lengthQualifier += minLength;
+    }
+    if (maxLength && !minLength) {
+      lengthQualifier += maxLength;
     }
+    if (minLength && maxLength) {
+      lengthQualifier += `${minLength} and ${maxLength}`;
+    }
+
     qualifierGroups.push(lengthQualifier);
   }
 
@@ -91,21 +118,33 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     typeof schema.exclusiveMaximum === "number"
   ) {
     let minmaxQualifier = "";
+    let minimum;
+    let maximum;
     if (typeof schema.exclusiveMinimum === "number") {
-      minmaxQualifier += `${schema.exclusiveMinimum} < `;
+      minimum = `\`> ${schema.exclusiveMinimum}\``;
     } else if (schema.minimum && !schema.exclusiveMinimum) {
-      minmaxQualifier += `${schema.minimum} ≤ `;
+      minimum = `\`>= ${schema.minimum}\``;
     } else if (schema.minimum && schema.exclusiveMinimum === true) {
-      minmaxQualifier += `${schema.minimum} < `;
+      minimum = `\`> ${schema.minimum}\``;
     }
-    minmaxQualifier += "value";
     if (typeof schema.exclusiveMaximum === "number") {
-      minmaxQualifier += ` < ${schema.exclusiveMaximum}`;
+      maximum = `\`< ${schema.exclusiveMaximum}\``;
     } else if (schema.maximum && !schema.exclusiveMaximum) {
-      minmaxQualifier += ` ≤ ${schema.maximum}`;
+      maximum = `\`<= ${schema.maximum}\``;
     } else if (schema.maximum && schema.exclusiveMaximum === true) {
-      minmaxQualifier += ` < ${schema.maximum}`;
+      maximum = `\`< ${schema.maximum}\``;
+    }
+
+    if (minimum && !maximum) {
+      minmaxQualifier += minimum;
+    }
+    if (maximum && !minimum) {
+      minmaxQualifier += maximum;
     }
+    if (minimum && maximum) {
+      minmaxQualifier += `${minimum} and ${maximum}`;
+    }
+
     qualifierGroups.push(minmaxQualifier);
   }
 
@@ -115,16 +154,23 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     );
   }
 
+  // Check if discriminator mapping
+  const discriminator = schema as any;
+  if (discriminator.mapping) {
+    const values = Object.keys(discriminator.mapping);
+    qualifierGroups.push(`[${values.map((e) => `\`${e}\``).join(", ")}]`);
+  }
+
   if (schema.enum) {
     qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
   }
 
   if (schema.minItems) {
-    qualifierGroups.push(`items >= ${schema.minItems}`);
+    qualifierGroups.push(`\`>= ${schema.minItems}\``);
   }
 
   if (schema.maxItems) {
-    qualifierGroups.push(`items <= ${schema.maxItems}`);
+    qualifierGroups.push(`\`<= ${schema.maxItems}\``);
   }
 
   if (qualifierGroups.length === 0) {

package/src/openapi/openapi.ts

@@ -13,7 +13,8 @@ import sdk from "@paloaltonetworks/postman-collection";
 import Collection from "@paloaltonetworks/postman-collection";
 import chalk from "chalk";
 import fs from "fs-extra";
-import { kebabCase } from "lodash";
+import cloneDeep from "lodash/cloneDeep";
+import kebabCase from "lodash/kebabCase";
 
 import { isURL } from "../index";
 import {
@@ -53,7 +54,8 @@ function jsonToCollection(data: OpenApiObject): Promise<Collection> {
 async function createPostmanCollection(
   openapiData: OpenApiObject
 ): Promise<Collection> {
-  const data = openapiData as OpenApiObject;
+  // Create copy of openapiData
+  const data = cloneDeep(openapiData) as OpenApiObject;
 
   // Including `servers` breaks postman, so delete all of them.
   delete data.servers;
@@ -101,7 +103,6 @@ function createItems(
           unversionedId: tagId,
           title: description ?? "",
           description: description ?? "",
-          slug: "/" + tagId,
           frontMatter: {},
           tag: {
             ...tag,
@@ -119,7 +120,6 @@ function createItems(
       unversionedId: infoId,
       title: openapiData.info.title,
       description: openapiData.info.description,
-      slug: "/" + infoId,
       frontMatter: {},
       securitySchemes: openapiData.components?.securitySchemes,
       info: {
@@ -128,6 +128,8 @@ function createItems(
           getTagDisplayName(tagName.name!, openapiData.tags ?? [])
         ),
         title: openapiData.info.title ?? "Introduction",
+        logo: openapiData.info["x-logo"]! as any,
+        darkLogo: openapiData.info["x-dark-logo"]! as any,
       },
     };
     items.push(infoPage);
@@ -146,7 +148,9 @@ function createItems(
           operationObject.summary ?? operationObject.operationId ?? "";
       }
 
-      const baseId = kebabCase(title);
+      const baseId = operationObject.operationId
+        ? kebabCase(operationObject.operationId)
+        : kebabCase(operationObject.summary);
 
       const servers =
         operationObject.servers ?? pathObject.servers ?? openapiData.servers;
@@ -181,7 +185,6 @@ function createItems(
         unversionedId: baseId,
         title: title,
         description: description ?? "",
-        slug: "/" + baseId,
         frontMatter: {},
         api: {
           ...defaults,

package/src/openapi/types.ts

@@ -42,6 +42,14 @@ 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 {

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -14,6 +14,7 @@ import chalk from "chalk";
 import { convertObj } from "swagger2openapi";
 
 import { OpenApiObject } from "../types";
+import { OpenAPIParser } from "./services/OpenAPIParser";
 
 function serializer(replacer: any, cycleReplacer: any) {
   var stack: any = [],
@@ -26,6 +27,18 @@ function serializer(replacer: any, cycleReplacer: any) {
     };
 
   return function (key: any, value: any) {
+    // Resolve discriminator ref pointers
+    if (value?.discriminator !== undefined) {
+      const parser = new OpenAPIParser(stack[0]);
+      for (let [k, v] of Object.entries(value.discriminator.mapping)) {
+        const discriminator = k as string;
+        if (typeof v === "string" && v.charAt(0) === "#") {
+          const ref = v as string;
+          const resolvedRef = parser.byRef(ref);
+          value.discriminator.mapping[discriminator] = resolvedRef;
+        }
+      }
+    }
     if (stack.length > 0) {
       // @ts-ignore
       var thisPos = stack.indexOf(this);

package/src/sidebars/index.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import path from "path";
+
 import {
   ProcessedSidebar,
   SidebarItemCategory,
@@ -139,8 +141,8 @@ function groupByTags(
           type: "generated-index" as "generated-index",
           title: tag,
           slug: label
-            ? "/category/" + kebabCase(label) + "/" + kebabCase(tag)
-            : "/category/" + kebabCase(tag),
+            ? path.join("/category", basePath, kebabCase(label), kebabCase(tag))
+            : path.join("/category", basePath, kebabCase(tag)),
         } as SidebarItemCategoryLinkConfig;
       }
 

package/src/types.ts

@@ -76,7 +76,7 @@ export interface ApiMetadataBase {
   description: string;
   source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
   sourceDirName: string; // relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
-  slug: string;
+  slug?: string;
   permalink: string;
   sidebarPosition?: number;
   frontMatter: Record<string, unknown>;