docusaurus-plugin-openapi-docs 4.0.0 → 4.1.0

package/README.md

@@ -41,9 +41,9 @@ Key Features:
 
 | Docusaurus OpenAPI Docs | Docusaurus      |
 | ----------------------- | --------------- |
-| 4.0.0 (current)         | `3.5.0 - 3.5.2` |
-| 3.0.2 (legacy)          | `3.0.1 - 3.4.0` |
-| 2.2.1 (legacy)          | `2.4.1 - 2.4.3` |
+| 4.0.x (current)         | `3.5.0 - 3.5.2` |
+| 3.0.x (end-of-support)  | `3.0.1 - 3.4.0` |
+| 2.2.3 (legacy)          | `2.4.1 - 2.4.3` |
 | 1.7.3 (end-of-support)  | `2.0.1 - 2.2.0` |
 
 ## Bootstrapping from Template (new Docusaurus site)
@@ -172,6 +172,8 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `markdownGenerators` | `object`  | `null`  | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options. |
 | `showSchemas`        | `boolean` | `null`  | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar.                                                              |
 
+### sidebarOptions
+
 `sidebarOptions` can be configured with the following options:
 
 | Name                 | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -181,6 +183,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `sidebarCollapsible` | `boolean` | `true`  | Whether sidebar categories are collapsible by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `sidebarCollapsed`   | `boolean` | `true`  | Whether sidebar categories are collapsed by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `customProps`        | `object`  | `null`  | Additional props for customizing a sidebar item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `sidebarGenerators`  | `object`  | `null`  | Optional: Customize sidebar rendering with callback functions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 > You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
 
@@ -206,6 +209,14 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `createTagPageMD`    | `function` | `null`  | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string`       |
 | `createSchemaPageMD` | `function` | `null`  | _Optional:_ Returns a string of the raw markdown body for schema pages.<br/><br/>**Function type:** `(pageData: SchemaPageMetadata) => string` |
 
+### sidebarGenerators
+
+`sidebarGenerators` can be configured with the following options:
+
+| Name            | Type       | Default | Description                                                                                                                                                                                                                                      |
+| --------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createDocItem` | `function` | `null`  | Optional: Returns a `SidebarItemDoc` object containing metadata for a sidebar item.<br/><br/>**Function type:** `(item: ApiPageMetadata \| SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc` |
+
 ## CLI Usage
 
 ```bash

package/lib/markdown/createCallbackMethodEndpoint.d.ts

@@ -0,0 +1 @@
+export declare function createCallbackMethodEndpoint(method: String, path: String): string[];

package/lib/markdown/createCallbackMethodEndpoint.js

@@ -0,0 +1,21 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCallbackMethodEndpoint = void 0;
+const utils_1 = require("./utils");
+function createCallbackMethodEndpoint(method, path) {
+    return [
+        (0, utils_1.create)("MethodEndpoint", {
+            method: method,
+            path: path,
+            context: "callback",
+        }),
+        "\n\n",
+    ];
+}
+exports.createCallbackMethodEndpoint = createCallbackMethodEndpoint;

package/lib/markdown/createCallbacks.js

@@ -7,8 +7,8 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCallbacks = void 0;
+const createCallbackMethodEndpoint_1 = require("./createCallbackMethodEndpoint");
 const createDescription_1 = require("./createDescription");
-const createMethodEndpoint_1 = require("./createMethodEndpoint");
 const createRequestBodyDetails_1 = require("./createRequestBodyDetails");
 const createStatusCodes_1 = require("./createStatusCodes");
 const utils_1 = require("./utils");
@@ -54,7 +54,7 @@ function createCallbacks({ callbacks }) {
                                 label: `${method.toUpperCase()} ${name}`,
                                 value: `${method}-${name}`,
                                 children: [
-                                    (0, createMethodEndpoint_1.createMethodEndpoint)(method, path),
+                                    (0, createCallbackMethodEndpoint_1.createCallbackMethodEndpoint)(method, path),
                                     // TODO: add `deprecation notice` when markdown support is added
                                     (0, createDescription_1.createDescription)(description),
                                     (0, createRequestBodyDetails_1.createRequestBodyDetails)({

package/lib/markdown/createDeprecationNotice.js

@@ -12,11 +12,10 @@ function createAdmonition({ children }) {
     return `:::caution deprecated\n\n${(0, utils_1.render)(children)}\n\n:::`;
 }
 function createDeprecationNotice({ deprecated, description, }) {
-    return (0, utils_1.guard)(deprecated, () => {
-        var _a;
-        return createAdmonition({
-            children: (_a = (0, utils_1.clean)(description)) !== null && _a !== void 0 ? _a : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
-        });
-    });
+    return (0, utils_1.guard)(deprecated, () => createAdmonition({
+        children: description && description.length > 0
+            ? (0, utils_1.clean)(description)
+            : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
+    }));
 }
 exports.createDeprecationNotice = createDeprecationNotice;

package/lib/markdown/createMethodEndpoint.js

@@ -9,6 +9,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMethodEndpoint = void 0;
 const utils_1 = require("./utils");
 function createMethodEndpoint(method, path) {
-    return [(0, utils_1.create)("MethodEndpoint", { method: method, path: path }), "\n\n"];
+    return [
+        (0, utils_1.create)("MethodEndpoint", {
+            method: method,
+            path: path,
+            context: "endpoint",
+        }),
+        "\n\n",
+    ];
 }
 exports.createMethodEndpoint = createMethodEndpoint;

package/lib/markdown/createParamsDetails.js

@@ -35,10 +35,16 @@ function createParamsDetails({ parameters, type }) {
             (0, utils_1.create)("div", {
                 children: [
                     (0, utils_1.create)("ul", {
-                        children: params.map((param) => (0, utils_1.create)("ParamsItem", {
-                            className: "paramsItem",
-                            param: param,
-                        })),
+                        children: params.map((param) => {
+                            var _a, _b, _c, _d, _e;
+                            return (0, utils_1.create)("ParamsItem", {
+                                className: "paramsItem",
+                                param: {
+                                    ...param,
+                                    enumDescriptions: Object.entries((_e = (_b = (_a = param === null || param === void 0 ? void 0 : param.schema) === null || _a === void 0 ? void 0 : _a["x-enumDescriptions"]) !== null && _b !== void 0 ? _b : (_d = (_c = param === null || param === void 0 ? void 0 : param.schema) === null || _c === void 0 ? void 0 : _c.items) === null || _d === void 0 ? void 0 : _d["x-enumDescriptions"]) !== null && _e !== void 0 ? _e : {}),
+                                },
+                            });
+                        }),
                     }),
                 ],
             }),

package/lib/markdown/createSchema.js

@@ -90,6 +90,10 @@ function createAnyOneOf(schema) {
                         anyOneChildren.push(createNodes(anyOneSchema, SCHEMA_TYPE));
                         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;
@@ -347,14 +351,14 @@ function createDetailsNode(name, schemaName, schema, required, nullable) {
                     (0, utils_1.create)("div", {
                         style: { marginLeft: "1rem" },
                         children: [
-                            (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
-                                style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                                children: (0, createDescription_1.createDescription)(message),
-                            })),
                             (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
                                 style: { marginTop: ".5rem", marginBottom: ".5rem" },
                                 children: (0, createDescription_1.createDescription)(description),
                             })),
+                            (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
+                                style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                                children: (0, createDescription_1.createDescription)(message),
+                            })),
                             createNodes(schema, SCHEMA_TYPE),
                         ],
                     }),
@@ -447,8 +451,9 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
     if (schema === undefined) {
         return undefined;
     }
+    // render as a simple property if there's no mapping
     if (discriminator.mapping === undefined) {
-        return undefined;
+        return createEdges({ name, schema, required });
     }
     return (0, utils_1.create)("div", {
         className: "openapi-discriminator__item openapi-schema__list-item",
@@ -473,17 +478,17 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
                         ]),
                     ],
                 }),
-                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(discriminator), (message) => (0, utils_1.create)("div", {
+                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
                     style: {
                         paddingLeft: "1rem",
                     },
-                    children: (0, createDescription_1.createDescription)(message),
+                    children: (0, createDescription_1.createDescription)(description),
                 })),
-                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
+                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(discriminator), (message) => (0, utils_1.create)("div", {
                     style: {
                         paddingLeft: "1rem",
                     },
-                    children: (0, createDescription_1.createDescription)(description),
+                    children: (0, createDescription_1.createDescription)(message),
                 })),
                 (0, utils_1.create)("DiscriminatorTabs", {
                     className: "openapi-tabs__discriminator",
@@ -538,38 +543,43 @@ function createEdges({ name, schema, required, discriminator, }) {
     }
     if (schema.allOf !== undefined) {
         const { mergedSchemas } = 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 = (0, schema_1.getSchemaName)(mergedSchemas);
-        if (mergedSchemas.oneOf !== undefined ||
-            mergedSchemas.anyOf !== undefined) {
-            return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
+        const mergedSchemaName = (0, schema_1.getSchemaName)(combinedSchemas);
+        if (name === "eventName") {
+            console.log(mergedSchemaName, combinedSchemas);
         }
-        if (mergedSchemas.properties !== undefined) {
-            return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
+        if (combinedSchemas.oneOf !== undefined ||
+            combinedSchemas.anyOf !== undefined) {
+            return createDetailsNode(name, mergedSchemaName, combinedSchemas, required, combinedSchemas.nullable);
+        }
+        if (combinedSchemas.properties !== undefined) {
+            return createDetailsNode(name, mergedSchemaName, combinedSchemas, required, combinedSchemas.nullable);
         }
-        if (mergedSchemas.additionalProperties !== undefined) {
-            return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
+        if (combinedSchemas.additionalProperties !== undefined) {
+            return createDetailsNode(name, mergedSchemaName, combinedSchemas, required, combinedSchemas.nullable);
         }
         // array of objects
         if (((_d = mergedSchemas.items) === null || _d === void 0 ? void 0 : _d.properties) !== undefined) {
-            return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
+            return createDetailsNode(name, mergedSchemaName, combinedSchemas, required, combinedSchemas.nullable);
         }
         return (0, utils_1.create)("SchemaItem", {
             collapsible: false,
             name,
             required: Array.isArray(required) ? required.includes(name) : required,
             schemaName: mergedSchemaName,
-            qualifierMessage: (0, schema_1.getQualifierMessage)(mergedSchemas),
-            schema: mergedSchemas,
+            qualifierMessage: (0, schema_1.getQualifierMessage)(combinedSchemas),
+            schema: combinedSchemas,
         });
     }
     // primitives and array of non-objects