docusaurus-plugin-openapi-docs 4.0.1 → 4.1.0

package/src/markdown/__snapshots__/createSchema.test.ts.snap

@@ -368,6 +368,93 @@ Array [
 ]
 `;
 
+exports[`createNodes anyOf should render oneOf within anyOf 1`] = `
+Array [
+  "<SchemaItem collapsible={true} className={\\"schemaItem\\"}>
+  <details style={{}} className={\\"openapi-markdown__details\\"}>
+    <summary style={{}}>
+      <span className={\\"openapi-schema__container\\"}>
+        <strong className={\\"openapi-schema__property\\"}>oneOfProperty</strong>
+        <span className={\\"openapi-schema__name\\"}>object</span>
+      </span>
+    </summary>
+    <div style={{ marginLeft: \\"1rem\\" }}>
+      <div>
+        <span className={\\"badge badge--info\\"} style={{ marginBottom: \\"1rem\\" }}>
+          anyOf
+        </span>
+        <SchemaTabs>
+          <TabItem label={\\"An int or a bool\\"} value={\\"0-item-properties\\"}>
+            <div>
+              <span
+                className={\\"badge badge--info\\"}
+                style={{ marginBottom: \\"1rem\\" }}
+              >
+                oneOf
+              </span>
+              <SchemaTabs>
+                <TabItem label={\\"MOD1\\"} value={\\"0-item-properties\\"}>
+                  <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+                    integer
+                  </div>
+                </TabItem>
+                <TabItem label={\\"MOD2\\"} value={\\"1-item-properties\\"}>
+                  <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+                    boolean
+                  </div>
+                </TabItem>
+              </SchemaTabs>
+            </div>
+          </TabItem>
+          <TabItem label={\\"MOD2\\"} value={\\"1-item-properties\\"}>
+            <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+              string
+            </div>
+          </TabItem>
+        </SchemaTabs>
+      </div>
+    </div>
+  </details>
+</SchemaItem>;
+",
+]
+`;
+
+exports[`createNodes anyOf should render primitives within anyOf 1`] = `
+Array [
+  "<SchemaItem collapsible={true} className={\\"schemaItem\\"}>
+  <details style={{}} className={\\"openapi-markdown__details\\"}>
+    <summary style={{}}>
+      <span className={\\"openapi-schema__container\\"}>
+        <strong className={\\"openapi-schema__property\\"}>oneOfProperty</strong>
+        <span className={\\"openapi-schema__name\\"}>object</span>
+      </span>
+    </summary>
+    <div style={{ marginLeft: \\"1rem\\" }}>
+      <div>
+        <span className={\\"badge badge--info\\"} style={{ marginBottom: \\"1rem\\" }}>
+          anyOf
+        </span>
+        <SchemaTabs>
+          <TabItem label={\\"MOD1\\"} value={\\"0-item-properties\\"}>
+            <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+              integer
+            </div>
+          </TabItem>
+          <TabItem label={\\"MOD2\\"} value={\\"1-item-properties\\"}>
+            <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+              boolean
+            </div>
+          </TabItem>
+        </SchemaTabs>
+      </div>
+    </div>
+  </details>
+</SchemaItem>;
+",
+]
+`;
+
 exports[`createNodes discriminator should handle basic discriminator with mapping 1`] = `
 Array [
   "<div>

package/src/markdown/createCallbackMethodEndpoint.ts

@@ -0,0 +1,19 @@
+/* ============================================================================
+ * 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 createCallbackMethodEndpoint(method: String, path: String) {
+  return [
+    create("MethodEndpoint", {
+      method: method,
+      path: path,
+      context: "callback",
+    }),
+    "\n\n",
+  ];
+}

package/src/markdown/createCallbacks.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { createCallbackMethodEndpoint } from "./createCallbackMethodEndpoint";
 import { createDescription } from "./createDescription";
-import { createMethodEndpoint } from "./createMethodEndpoint";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
 import { create } from "./utils";
@@ -78,7 +78,7 @@ export function createCallbacks({ callbacks }: Props) {
                 label: `${method.toUpperCase()} ${name}`,
                 value: `${method}-${name}`,
                 children: [
-                  createMethodEndpoint(method, path),
+                  createCallbackMethodEndpoint(method, path),
                   // TODO: add `deprecation notice` when markdown support is added
                   createDescription(description),
                   createRequestBodyDetails({

package/src/markdown/createDeprecationNotice.ts

@@ -23,8 +23,9 @@ export function createDeprecationNotice({
   return guard(deprecated, () =>
     createAdmonition({
       children:
-        clean(description) ??
-        "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
+        description && description.length > 0
+          ? clean(description)
+          : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
     })
   );
 }

package/src/markdown/createMethodEndpoint.ts

@@ -8,5 +8,12 @@
 import { create } from "./utils";
 
 export function createMethodEndpoint(method: String, path: String) {
-  return [create("MethodEndpoint", { method: method, path: path }), "\n\n"];
+  return [
+    create("MethodEndpoint", {
+      method: method,
+      path: path,
+      context: "endpoint",
+    }),
+    "\n\n",
+  ];
 }

package/src/markdown/createParamsDetails.ts

@@ -43,12 +43,19 @@ export function createParamsDetails({ parameters, type }: Props) {
       create("div", {
         children: [
           create("ul", {
-            children: params.map((param) =>
-              create("ParamsItem", {
+            children: params.map((param) => {
+              return create("ParamsItem", {
                 className: "paramsItem",
-                param: param,
-              })
-            ),
+                param: {
+                  ...param,
+                  enumDescriptions: Object.entries(
+                    param?.schema?.["x-enumDescriptions"] ??
+                      param?.schema?.items?.["x-enumDescriptions"] ??
+                      {}
+                  ),
+                },
+              });
+            }),
           }),
         ],
       }),

package/src/markdown/createSchema.test.ts

@@ -246,6 +246,70 @@ describe("createNodes", () => {
     });
   });
 
+  describe("anyOf", () => {
+    it("should render primitives within anyOf", async () => {
+      const schema: SchemaObject = {
+        type: "object",
+        properties: {
+          oneOfProperty: {
+            anyOf: [
+              {
+                type: "integer",
+              },
+              {
+                type: "boolean",
+              },
+            ],
+            title: "One of int or bool",
+          },
+        },
+      };
+
+      expect(
+        await Promise.all(
+          createNodes(schema, "response").map(
+            async (md: any) => await prettier.format(md, { parser: "babel" })
+          )
+        )
+      ).toMatchSnapshot();
+    });
+
+    it("should render oneOf within anyOf", async () => {
+      const schema: SchemaObject = {
+        type: "object",
+        properties: {
+          oneOfProperty: {
+            anyOf: [
+              {
+                oneOf: [
+                  {
+                    type: "integer",
+                  },
+                  {
+                    type: "boolean",
+                  },
+                ],
+                title: "An int or a bool",
+              },
+              {
+                type: "string",
+              },
+            ],
+            title: "One of int or bool, or a string",
+          },
+        },
+      };
+
+      expect(
+        await Promise.all(
+          createNodes(schema, "response").map(
+            async (md: any) => await prettier.format(md, { parser: "babel" })
+          )
+        )
+      ).toMatchSnapshot();
+    });
+  });
+
   describe("allOf", () => {
     it("should render same-level properties with allOf", async () => {
       const schema: SchemaObject = {

package/src/markdown/createSchema.ts

@@ -104,6 +104,11 @@ function createAnyOneOf(schema: SchemaObject): any {
             delete anyOneSchema.allOf;
           }
 
+          if (anyOneSchema.oneOf !== undefined) {
+            anyOneChildren.push(createNodes(anyOneSchema, SCHEMA_TYPE));
+            delete anyOneSchema.oneOf;
+          }
+
           if (anyOneSchema.items !== undefined) {
             anyOneChildren.push(createItems(anyOneSchema));
             delete anyOneSchema.items;
@@ -411,16 +416,16 @@ function createDetailsNode(
           create("div", {
             style: { marginLeft: "1rem" },
             children: [
-              guard(getQualifierMessage(schema), (message) =>
+              guard(schema.description, (description) =>
                 create("div", {
                   style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                  children: createDescription(message),
+                  children: createDescription(description),
                 })
               ),
-              guard(schema.description, (description) =>
+              guard(getQualifierMessage(schema), (message) =>
                 create("div", {
                   style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                  children: createDescription(description),
+                  children: createDescription(message),
                 })
               ),
               createNodes(schema, SCHEMA_TYPE),
@@ -554,20 +559,20 @@ function createPropertyDiscriminator(
             ]),
           ],
         }),
-        guard(getQualifierMessage(discriminator), (message) =>
+        guard(schema.description, (description) =>
           create("div", {
             style: {
               paddingLeft: "1rem",
             },
-            children: createDescription(message),
+            children: createDescription(description),
           })
         ),
-        guard(schema.description, (description) =>
+        guard(getQualifierMessage(discriminator), (message) =>
           create("div", {
             style: {
               paddingLeft: "1rem",
             },
-            children: createDescription(description),
+            children: createDescription(message),
           })
         ),
         create("DiscriminatorTabs", {
@@ -682,50 +687,57 @@ function createEdges({
     const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
       schema.allOf
     );
+    delete schema.allOf;
+    const combinedSchemas = { ...schema, ...mergedSchemas };
 
     if (SCHEMA_TYPE === "request") {
-      if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
+      if (combinedSchemas.readOnly && combinedSchemas.readOnly === true) {
         return undefined;
       }
     }
 
     if (SCHEMA_TYPE === "response") {
-      if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
+      if (combinedSchemas.writeOnly && combinedSchemas.writeOnly === true) {
         return undefined;
       }
     }
 
-    const mergedSchemaName = getSchemaName(mergedSchemas);
+    const mergedSchemaName = getSchemaName(combinedSchemas);
+
+    if (name === "eventName") {
+      console.log(mergedSchemaName, combinedSchemas);
+    }
+
     if (
-      mergedSchemas.oneOf !== undefined ||
-      mergedSchemas.anyOf !== undefined
+      combinedSchemas.oneOf !== undefined ||
+      combinedSchemas.anyOf !== undefined
     ) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        mergedSchemas,
+        combinedSchemas,
         required,
-        schema.nullable
+        combinedSchemas.nullable
       );
     }
 
-    if (mergedSchemas.properties !== undefined) {
+    if (combinedSchemas.properties !== undefined) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        mergedSchemas,
+        combinedSchemas,
         required,
-        schema.nullable
+        combinedSchemas.nullable
       );
     }
 
-    if (mergedSchemas.additionalProperties !== undefined) {
+    if (combinedSchemas.additionalProperties !== undefined) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        mergedSchemas,
+        combinedSchemas,
         required,
-        schema.nullable
+        combinedSchemas.nullable
       );
     }
 
@@ -734,9 +746,9 @@ function createEdges({
       return createDetailsNode(
         name,
         mergedSchemaName,
-        mergedSchemas,
+        combinedSchemas,
         required,
-        schema.nullable
+        combinedSchemas.nullable
       );
     }
 
@@ -745,8 +757,8 @@ function createEdges({
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
       schemaName: mergedSchemaName,
-      qualifierMessage: getQualifierMessage(mergedSchemas),
-      schema: mergedSchemas,
+      qualifierMessage: getQualifierMessage(combinedSchemas),
+      schema: combinedSchemas,
     });
   }
 

package/src/markdown/utils.ts

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+/**
+ * Children in the plugin does not accept DOM elements, when compared with Children in the theme.
+ * It is designed for rendering HTML a strings.
+ */
 export type Children = string | undefined | (string | string[] | undefined)[];
 
 export type Props = Record<string, any> & { children?: Children };

package/src/openapi/openapi.ts

@@ -269,7 +269,7 @@ function createItems(
 
   // Gather x-webhooks endpoints
   for (let [path, pathObject] of Object.entries(
-    openapiData["x-webhooks"] ?? {}
+    openapiData["x-webhooks"] ?? openapiData["webhooks"] ?? {}
   )) {
     path = "webhook";
     const { $ref, description, parameters, servers, summary, ...rest } =

package/src/openapi/types.ts

@@ -21,6 +21,7 @@ export interface OpenApiObject {
   tags?: TagObject[];
   externalDocs?: ExternalDocumentationObject;
   swagger?: string;
+  webhooks?: PathsObject;
   "x-webhooks"?: PathsObject;
   "x-tagGroups"?: TagGroupObject[];
 }
@@ -197,6 +198,7 @@ export interface ParameterObject {
   param?: Object;
   // ignoring stylings: matrix, label, form, simple, spaceDelimited,
   // pipeDelimited and deepObject
+  "x-enumDescriptions"?: Record<string, string>;
 }
 
 export interface ParameterObjectWithRef {
@@ -353,6 +355,7 @@ export type SchemaObject = Omit<
   example?: any;
   deprecated?: boolean;
   "x-tags"?: string[];
+  "x-enumDescriptions"?: Record<string, string>;
 };
 
 export type SchemaObjectWithRef = Omit<

package/src/openapi/utils/services/OpenAPIParser.ts

@@ -270,6 +270,7 @@ export class OpenAPIParser {
       const {
         type,
         enum: enumProperty,
+        "x-enumDescription": enumDescription,
         properties,
         items,
         required,

package/src/options.ts

@@ -7,12 +7,17 @@
 
 import { Joi } from "@docusaurus/utils-validation";
 
+const sidebarGenerators = Joi.object({
+  createDocItem: Joi.function(),
+});
+
 const sidebarOptions = Joi.object({
   groupPathsBy: Joi.string().valid("tag", "tagGroup"),
   categoryLinkSource: Joi.string().valid("tag", "info", "auto"),
   customProps: Joi.object(),
   sidebarCollapsible: Joi.boolean(),
   sidebarCollapsed: Joi.boolean(),
+  sidebarGenerators: sidebarGenerators,
 });
 
 const markdownGenerators = Joi.object({

package/src/sidebars/index.ts

@@ -12,7 +12,6 @@ import {
   ProcessedSidebar,
   SidebarItemCategory,
   SidebarItemCategoryLinkConfig,
-  SidebarItemDoc,
 } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import { posixPath } from "@docusaurus/utils";
 import clsx from "clsx";
@@ -27,6 +26,7 @@ import type {
   ApiMetadata,
   InfoPageMetadata,
   SchemaPageMetadata,
+  ApiDocItemGenerator,
 } from "../types";
 
 function isApiItem(item: ApiMetadata): item is ApiMetadata {
@@ -41,6 +41,37 @@ function isSchemaItem(item: ApiMetadata): item is ApiMetadata {
   return item.type === "schema";
 }
 
+const createDocItem: ApiDocItemGenerator = (
+  item,
+  { sidebarOptions: { customProps }, basePath }
+) => {
+  const sidebar_label = item.frontMatter.sidebar_label;
+  const title = item.title;
+  const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
+  const className =
+    item.type === "api"
+      ? clsx(
+          {
+            "menu__list-item--deprecated": item.api.deprecated,
+            "api-method": !!item.api.method,
+          },
+          item.api.method
+        )
+      : clsx(
+          {
+            "menu__list-item--deprecated": item.schema.deprecated,
+          },
+          "schema"
+        );
+  return {
+    type: "doc" as const,
+    id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+    label: (sidebar_label as string) ?? title ?? id,
+    customProps: customProps,
+    className: className ? className : undefined,
+  };
+};
+
 function groupByTags(
   items: ApiMetadata[],
   sidebarOptions: SidebarOptions,
@@ -53,12 +84,8 @@ function groupByTags(
   // Remove trailing slash before proceeding
   outputDir = outputDir.replace(/\/$/, "");
 
-  const {
-    sidebarCollapsed,
-    sidebarCollapsible,
-    customProps,
-    categoryLinkSource,
-  } = sidebarOptions;
+  const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } =
+    sidebarOptions;
 
   const apiItems = items.filter(isApiItem) as ApiPageMetadata[];
   const infoItems = items.filter(isInfoItem) as InfoPageMetadata[];
@@ -101,35 +128,13 @@ function groupByTags(
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
     : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
-  function createDocItem(
-    item: ApiPageMetadata | SchemaPageMetadata
-  ): SidebarItemDoc {
-    const sidebar_label = item.frontMatter.sidebar_label;
-    const title = item.title;
-    const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
-    const className =
-      item.type === "api"
-        ? clsx(
-            {
-              "menu__list-item--deprecated": item.api.deprecated,
-              "api-method": !!item.api.method,
-            },
-            item.api.method
-          )
-        : clsx(
-            {
-              "menu__list-item--deprecated": item.schema.deprecated,
-            },
-            "schema"
-          );
-    return {
-      type: "doc" as const,
-      id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
-      label: (sidebar_label as string) ?? title ?? id,
-      customProps: customProps,
-      className: className ? className : undefined,
-    };
-  }
+
+  const createDocItemFnContext = {
+    sidebarOptions,
+    basePath,
+  };
+  const createDocItemFn =
+    sidebarOptions.sidebarGenerators?.createDocItem ?? createDocItem;
 
   let rootIntroDoc = undefined;
   if (infoItems.length === 1) {
@@ -208,7 +213,9 @@ function groupByTags(
         link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
-        items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
+        items: [...taggedSchemaItems, ...taggedApiItems].map((item) =>
+          createDocItemFn(item, createDocItemFnContext)
+        ),
       };
     })
     .filter((item) => item.items.length > 0); // Filter out any categories with no items.
@@ -216,7 +223,7 @@ function groupByTags(
   // Handle items with no tag
   const untaggedItems = apiItems
     .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-    .map(createDocItem);
+    .map((item) => createDocItemFn(item, createDocItemFnContext));
   let untagged: SidebarItemCategory[] = [];
   if (untaggedItems.length > 0) {
     untagged = [
@@ -227,7 +234,7 @@ function groupByTags(
         collapsed: sidebarCollapsed!,
         items: apiItems
           .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-          .map(createDocItem),
+          .map((item) => createDocItemFn(item, createDocItemFnContext)),
       },
     ];
   }
@@ -242,7 +249,7 @@ function groupByTags(
         collapsed: sidebarCollapsed!,
         items: schemaItems
           .filter(({ schema }) => !schema["x-tags"])
-          .map(createDocItem),
+          .map((item) => createDocItemFn(item, createDocItemFnContext)),
       },
     ];
   }

package/src/types.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import type Request from "postman-collection";
 
 import {
@@ -57,12 +58,22 @@ export interface MarkdownGenerator {
   createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
 }
 
+export type ApiDocItemGenerator = (
+  item: ApiPageMetadata | SchemaPageMetadata,
+  context: { sidebarOptions: SidebarOptions; basePath: string }
+) => SidebarItemDoc;
+
+export interface SidebarGenerators {
+  createDocItem?: ApiDocItemGenerator;
+}
+
 export interface SidebarOptions {
   groupPathsBy?: string;
   categoryLinkSource?: "info" | "tag" | "auto";
   customProps?: { [key: string]: unknown };
   sidebarCollapsible?: boolean;
   sidebarCollapsed?: boolean;
+  sidebarGenerators?: SidebarGenerators;
 }
 
 export interface APIVersionOptions {