docusaurus-plugin-openapi-docs 4.4.0 → 4.5.1

package/README.md

@@ -41,17 +41,17 @@ Key Features:
 
 | Docusaurus OpenAPI Docs | Docusaurus      |
 | ----------------------- | --------------- |
-| 4.0.x (current)         | `3.5.0 - 3.7.x` |
+| 4.0.x (current)         | `3.5.0 - 3.8.1` |
 | 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)
 
-Run the following to bootstrap a Docsaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
+Run the following to bootstrap a Docusaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
 
 ```bash
-npx create-docusaurus@3.7.0 my-website --package-manager yarn
+npx create-docusaurus@3.8.1 my-website --package-manager yarn
 ```
 
 > When prompted to select a template choose `Git repository`.
@@ -189,15 +189,17 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `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`.
+> Use `x-position` vendor extension (or the front matter `position`) on operations to explicitly order sidebar items.
 
 `versions` can be configured with the following options:
 
-| Name       | Type     | Default | Description                                                                                                              |
-| ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `specPath` | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of micro OpenAPI specification files. |
-| `ouputDir` | `string` | `null`  | Desired output path for versioned, generated MDX files.                                                                  |
-| `label`    | `string` | `null`  | _Optional:_ Version label used when generating version selector dropdown menu.                                           |
-| `baseUrl`  | `string` | `null`  | _Optional:_ Version base URL used when generating version selector dropdown menu.                                        |
+| Name          | Type     | Default | Description                                                                                                                |
+| ------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `specPath`    | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or a directory of micro OpenAPI specification files. |
+| `outputDir`   | `string` | `null`  | Desired output path for versioned, generated MDX files.                                                                    |
+| `label`       | `string` | `null`  | _Optional:_ Version label used when generating the version selector dropdown menu.                                         |
+| `baseUrl`     | `string` | `null`  | _Optional:_ Version base URL used when generating the version selector dropdown menu.                                      |
+| `downloadUrl` | `string` | `null`  | _Optional:_ Designated URL for downloading the versioned OpenAPI specification.                                            |
 
 > All versions will automatically inherit `sidebarOptions` from the parent/base config.
 
@@ -329,11 +331,11 @@ yarn docusaurus gen-api-docs:version petstore:all
 
 > This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `versions` config and will also generate a `versions.json` file.
 
-> Substitue `all` with a specific version ID to generate/clean a specific version. Generating for `all` or a specific version ID will automatically update the `versions.json` file.
+> Substitute `all` with a specific version ID to generate or clean a specific version. Generating for `all` or a single version ID will automatically update the `versions.json` file.
 
 ## Developer Quick Start
 
-> Looking to make a contribution? Make sure to checkout out our contributing guide.
+> Looking to make a contribution? Make sure to check out our contributing guide.
 
 After [forking](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/fork) the main repository, run the following:
 

package/lib/markdown/createAuthentication.js

@@ -13,7 +13,7 @@ function createAuthentication(securitySchemes) {
     if (!securitySchemes || !Object.keys(securitySchemes).length)
         return "";
     const createAuthenticationTable = (securityScheme) => {
-        const { bearerFormat, flows, name, scheme, type, openIdConnectUrl } = securityScheme;
+        const { bearerFormat, flows, name, scheme, type, openIdConnectUrl, in: paramIn, } = securityScheme;
         const createSecuritySchemeTypeRow = () => (0, utils_1.create)("tr", {
             children: [
                 (0, utils_1.create)("th", { children: "Security Scheme Type:" }),
@@ -54,7 +54,9 @@ function createAuthentication(securitySchemes) {
                                     createSecuritySchemeTypeRow(),
                                     (0, utils_1.create)("tr", {
                                         children: [
-                                            (0, utils_1.create)("th", { children: "Header parameter name:" }),
+                                            (0, utils_1.create)("th", {
+                                                children: `${paramIn.charAt(0).toUpperCase() + paramIn.slice(1)} parameter name:`,
+                                            }),
                                             (0, utils_1.create)("td", { children: name }),
                                         ],
                                     }),

package/lib/markdown/schema.js

@@ -11,6 +11,9 @@ exports.getQualifierMessage = getQualifierMessage;
 function prettyName(schema, circular) {
     var _a, _b, _c, _d, _e;
     if (schema.format) {
+        if (schema.type) {
+            return `${schema.type}<${schema.format}>`;
+        }
         return schema.format;
     }
     if (schema.allOf) {

package/lib/openapi/createRequestExample.js

@@ -5,187 +5,10 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sampleRequestFromSchema = void 0;
-const chalk_1 = __importDefault(require("chalk"));
-const merge_1 = __importDefault(require("lodash/merge"));
-const createSchema_1 = require("../markdown/createSchema");
-const primitives = {
-    string: {
-        default: () => "string",
-        email: () => "user@example.com",
-        date: () => "2024-07-29",
-        "date-time": () => "2024-07-29T15:51:28.071Z",
-        uuid: () => "3fa85f64-5717-4562-b3fc-2c963f66afa6",
-        hostname: () => "example.com",
-        ipv4: () => "198.51.100.42",
-        ipv6: () => "2001:0db8:5b96:0000:0000:426f:8e17:642a",
-    },
-    number: {
-        default: () => 0,
-        float: () => 0.0,
-    },
-    integer: {
-        default: () => 0,
-    },
-    boolean: {
-        default: (schema) => typeof schema.default === "boolean" ? schema.default : true,
-    },
-    object: {},
-    array: {},
-};
-function sampleRequestFromProp(name, prop, obj) {
-    // Handle resolved circular props
-    if (typeof prop === "object" && Object.keys(prop).length === 0) {
-        obj[name] = prop;
-        return obj;
-    }
-    // TODO: handle discriminators
-    if (prop.oneOf) {
-        obj[name] = (0, exports.sampleRequestFromSchema)(prop.oneOf[0]);
-    }
-    else if (prop.anyOf) {
-        obj[name] = (0, exports.sampleRequestFromSchema)(prop.anyOf[0]);
-    }
-    else if (prop.allOf) {
-        const mergedSchemas = (0, createSchema_1.mergeAllOf)(prop);
-        sampleRequestFromProp(name, mergedSchemas, obj);
-    }
-    else {
-        obj[name] = (0, exports.sampleRequestFromSchema)(prop);
-    }
-    return obj;
-}
+const createSchemaExample_1 = require("./createSchemaExample");
 const sampleRequestFromSchema = (schema = {}) => {
-    try {
-        // deep copy schema before processing
-        let schemaCopy = JSON.parse(JSON.stringify(schema));
-        let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
-        if (example !== undefined) {
-            return example;
-        }
-        if (oneOf) {
-            if (properties) {
-                const combinedSchemas = (0, merge_1.default)(schemaCopy, oneOf[0]);
-                delete combinedSchemas.oneOf;
-                return (0, exports.sampleRequestFromSchema)(combinedSchemas);
-            }
-            // Just go with first schema
-            return (0, exports.sampleRequestFromSchema)(oneOf[0]);
-        }
-        if (anyOf) {
-            if (properties) {
-                const combinedSchemas = (0, merge_1.default)(schemaCopy, anyOf[0]);
-                delete combinedSchemas.anyOf;
-                return (0, exports.sampleRequestFromSchema)(combinedSchemas);
-            }
-            // Just go with first schema
-            return (0, exports.sampleRequestFromSchema)(anyOf[0]);
-        }
-        if (allOf) {
-            const mergedSchemas = (0, createSchema_1.mergeAllOf)(schemaCopy);
-            if (mergedSchemas.properties) {
-                for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-                    if ((value.readOnly && value.readOnly === true) || value.deprecated) {
-                        delete mergedSchemas.properties[key];
-                    }
-                }
-            }
-            if (properties) {
-                const combinedSchemas = (0, merge_1.default)(schemaCopy, mergedSchemas);
-                delete combinedSchemas.allOf;
-                return (0, exports.sampleRequestFromSchema)(combinedSchemas);
-            }
-            return (0, exports.sampleRequestFromSchema)(mergedSchemas);
-        }
-        if (!type) {
-            if (properties) {
-                type = "object";
-            }
-            else if (items) {
-                type = "array";
-            }
-            else {
-                return;
-            }
-        }
-        if (type === "object") {
-            let obj = {};
-            for (let [name, prop] of Object.entries(properties !== null && properties !== void 0 ? properties : {})) {
-                if (prop.properties) {
-                    for (const [key, value] of Object.entries(prop.properties)) {
-                        if ((value.readOnly && value.readOnly === true) ||
-                            value.deprecated) {
-                            delete prop.properties[key];
-                        }
-                    }
-                }
-                if (prop.items && prop.items.properties) {
-                    for (const [key, value] of Object.entries(prop.items.properties)) {
-                        if ((value.readOnly && value.readOnly === true) ||
-                            value.deprecated) {
-                            delete prop.items.properties[key];
-                        }
-                    }
-                }
-                if (prop.readOnly && prop.readOnly === true) {
-                    continue;
-                }
-                if (prop.deprecated) {
-                    continue;
-                }
-                // Resolve schema from prop recursively
-                obj = sampleRequestFromProp(name, prop, obj);
-            }
-            return obj;
-        }
-        if (type === "array") {
-            if (Array.isArray(items === null || items === void 0 ? void 0 : items.anyOf)) {
-                return items === null || items === void 0 ? void 0 : items.anyOf.map((item) => (0, exports.sampleRequestFromSchema)(item));
-            }
-            if (Array.isArray(items === null || items === void 0 ? void 0 : items.oneOf)) {
-                return items === null || items === void 0 ? void 0 : items.oneOf.map((item) => (0, exports.sampleRequestFromSchema)(item));
-            }
-            return normalizeArray((0, exports.sampleRequestFromSchema)(items));
-        }
-        if (schemaCopy.enum) {
-            if (schemaCopy.default) {
-                return schemaCopy.default;
-            }
-            return normalizeArray(schemaCopy.enum)[0];
-        }
-        if ((schema.readOnly && schema.readOnly === true) ||
-            schemaCopy.deprecated) {
-            return undefined;
-        }
-        return primitive(schemaCopy);
-    }
-    catch (err) {
-        console.error(chalk_1.default.yellow("WARNING: failed to create example from schema object:", err));
-        return;
-    }
+    return (0, createSchemaExample_1.sampleFromSchema)(schema, { type: "request" });
 };
 exports.sampleRequestFromSchema = sampleRequestFromSchema;
-function primitive(schema = {}) {
-    let { type, format } = schema;
-    if (type === undefined) {
-        return;
-    }
-    let fn = schema.default ? () => schema.default : primitives[type].default;
-    if (format !== undefined) {
-        fn = primitives[type][format] || fn;
-    }
-    if (fn) {
-        return fn(schema);
-    }
-    return "Unknown Type: " + schema.type;
-}
-function normalizeArray(arr) {
-    if (Array.isArray(arr)) {
-        return arr;
-    }
-    return [arr];
-}

package/lib/openapi/createResponseExample.js

@@ -5,188 +5,10 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sampleResponseFromSchema = void 0;
-const chalk_1 = __importDefault(require("chalk"));
-const merge_1 = __importDefault(require("lodash/merge"));
-const createSchema_1 = require("../markdown/createSchema");
-const primitives = {
-    string: {
-        default: () => "string",
-        email: () => "user@example.com",
-        date: () => "2024-07-29",
-        "date-time": () => "2024-07-29T15:51:28.071Z",
-        uuid: () => "3fa85f64-5717-4562-b3fc-2c963f66afa6",
-        hostname: () => "example.com",
-        ipv4: () => "198.51.100.42",
-        ipv6: () => "2001:0db8:5b96:0000:0000:426f:8e17:642a",
-    },
-    number: {
-        default: () => 0,
-        float: () => 0.0,
-    },
-    integer: {
-        default: () => 0,
-    },
-    boolean: {
-        default: (schema) => typeof schema.default === "boolean" ? schema.default : true,
-    },
-    object: {},
-    array: {},
-};
-function sampleResponseFromProp(name, prop, obj) {
-    // Handle resolved circular props
-    if (typeof prop === "object" && Object.keys(prop).length === 0) {
-        obj[name] = prop;
-        return obj;
-    }
-    // TODO: handle discriminators
-    if (prop.oneOf) {
-        obj[name] = (0, exports.sampleResponseFromSchema)(prop.oneOf[0]);
-    }
-    else if (prop.anyOf) {
-        obj[name] = (0, exports.sampleResponseFromSchema)(prop.anyOf[0]);
-    }
-    else if (prop.allOf) {
-        const mergedSchemas = (0, createSchema_1.mergeAllOf)(prop);
-        sampleResponseFromProp(name, mergedSchemas, obj);
-    }
-    else {
-        obj[name] = (0, exports.sampleResponseFromSchema)(prop);
-    }
-    return obj;
-}
+const createSchemaExample_1 = require("./createSchemaExample");
 const sampleResponseFromSchema = (schema = {}) => {
-    try {
-        // deep copy schema before processing
-        let schemaCopy = JSON.parse(JSON.stringify(schema));
-        let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
-        if (example !== undefined) {
-            return example;
-        }
-        if (allOf) {
-            const mergedSchemas = (0, createSchema_1.mergeAllOf)(schemaCopy);
-            if (mergedSchemas.properties) {
-                for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-                    if ((value.writeOnly && value.writeOnly === true) ||
-                        value.deprecated) {
-                        delete mergedSchemas.properties[key];
-                    }
-                }
-            }
-            if (properties) {
-                const combinedSchemas = (0, merge_1.default)(schemaCopy, mergedSchemas);
-                delete combinedSchemas.allOf;
-                return (0, exports.sampleResponseFromSchema)(combinedSchemas);
-            }
-            return (0, exports.sampleResponseFromSchema)(mergedSchemas);
-        }
-        if (oneOf) {
-            if (properties) {
-                const combinedSchemas = (0, merge_1.default)(schemaCopy, oneOf[0]);
-                delete combinedSchemas.oneOf;
-                return (0, exports.sampleResponseFromSchema)(combinedSchemas);
-            }
-            // Just go with first schema
-            return (0, exports.sampleResponseFromSchema)(oneOf[0]);
-        }
-        if (anyOf) {
-            if (properties) {
-                const combinedSchemas = (0, merge_1.default)(schemaCopy, anyOf[0]);
-                delete combinedSchemas.anyOf;
-                return (0, exports.sampleResponseFromSchema)(combinedSchemas);
-            }
-            // Just go with first schema
-            return (0, exports.sampleResponseFromSchema)(anyOf[0]);
-        }
-        if (!type) {
-            if (properties) {
-                type = "object";
-            }
-            else if (items) {
-                type = "array";
-            }
-            else {
-                return;
-            }
-        }
-        if (type === "object") {
-            let obj = {};
-            for (let [name, prop] of Object.entries(properties !== null && properties !== void 0 ? properties : {})) {
-                if (prop.properties) {
-                    for (const [key, value] of Object.entries(prop.properties)) {
-                        if ((value.writeOnly && value.writeOnly === true) ||
-                            value.deprecated) {
-                            delete prop.properties[key];
-                        }
-                    }
-                }
-                if (prop.items && prop.items.properties) {
-                    for (const [key, value] of Object.entries(prop.items.properties)) {
-                        if ((value.writeOnly && value.writeOnly === true) ||
-                            value.deprecated) {
-                            delete prop.items.properties[key];
-                        }
-                    }
-                }
-                if (prop.writeOnly && prop.writeOnly === true) {
-                    continue;
-                }
-                if (prop.deprecated) {
-                    continue;
-                }
-                // Resolve schema from prop recursively
-                obj = sampleResponseFromProp(name, prop, obj);
-            }
-            return obj;
-        }
-        if (type === "array") {
-            if (Array.isArray(items === null || items === void 0 ? void 0 : items.anyOf)) {
-                return items === null || items === void 0 ? void 0 : items.anyOf.map((item) => (0, exports.sampleResponseFromSchema)(item));
-            }
-            if (Array.isArray(items === null || items === void 0 ? void 0 : items.oneOf)) {
-                return items === null || items === void 0 ? void 0 : items.oneOf.map((item) => (0, exports.sampleResponseFromSchema)(item));
-            }
-            return [(0, exports.sampleResponseFromSchema)(items)];
-        }
-        if (schemaCopy.enum) {
-            if (schemaCopy.default) {
-                return schemaCopy.default;
-            }
-            return normalizeArray(schemaCopy.enum)[0];
-        }
-        if ((schemaCopy.writeOnly && schemaCopy.writeOnly === true) ||
-            schemaCopy.deprecated) {
-            return undefined;
-        }
-        return primitive(schemaCopy);
-    }
-    catch (err) {
-        console.error(chalk_1.default.yellow("WARNING: failed to create example from schema object:", err));
-        return;
-    }
+    return (0, createSchemaExample_1.sampleFromSchema)(schema, { type: "response" });
 };
 exports.sampleResponseFromSchema = sampleResponseFromSchema;
-function primitive(schema = {}) {
-    let { type, format } = schema;
-    if (type === undefined) {
-        return;
-    }
-    let fn = schema.default ? () => schema.default : primitives[type].default;
-    if (format !== undefined) {
-        fn = primitives[type][format] || fn;
-    }
-    if (fn) {
-        return fn(schema);
-    }
-    return "Unknown Type: " + schema.type;
-}
-function normalizeArray(arr) {
-    if (Array.isArray(arr)) {
-        return arr;
-    }
-    return [arr];
-}

package/lib/openapi/createSchemaExample.d.ts

@@ -0,0 +1,7 @@
+import { SchemaObject } from "./types";
+type ExampleType = "request" | "response";
+interface ExampleContext {
+    type: ExampleType;
+}
+export declare const sampleFromSchema: (schema: SchemaObject | undefined, context: ExampleContext) => any;
+export {};