docusaurus-plugin-openapi-docs 1.4.7 → 1.5.1-hotfix1

package/README.md

@@ -121,6 +121,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `specPath`       | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
 | `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
+| `proxy`          | `string` | `null`  | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser.                                     |
 | `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
 | `downloadUrl`    | `string` | `null`  | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc)                             |
 | `sidebarOptions` | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                            |

package/lib/index.js

@@ -87,8 +87,8 @@ function pluginOpenAPIDocs(context, options) {
             ? specPath
             : path_1.default.resolve(siteDir, specPath);
         try {
-            const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath, options);
-            const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, sidebarOptions);
+            const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath);
+            const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, options, sidebarOptions);
             if (!fs_1.default.existsSync(outputDir)) {
                 try {
                     fs_1.default.mkdirSync(outputDir, { recursive: true });
@@ -143,6 +143,10 @@ sidebar_class_name: "{{{api.method}}} api-method"
 {{#infoPath}}
 info_path: {{{infoPath}}}
 {{/infoPath}}
+custom_edit_url: null
+{{#frontMatter.proxy}}
+proxy: {{{frontMatter.proxy}}}
+{{/frontMatter.proxy}}
 ---
 
 {{{markdown}}}

package/lib/markdown/createDescription.js

@@ -13,7 +13,9 @@ function createDescription(description) {
         return "";
     }
     return `\n\n${description
-        .replace(utils_1.lessThan, "<")
-        .replace(utils_1.greaterThan, ">")}\n\n`;
+        .replace(utils_1.greaterThan, "\\>")
+        .replace(utils_1.codeFence, function (match) {
+        return match.replace(/\\>/g, ">");
+    })}\n\n`;
 }
 exports.createDescription = createDescription;

package/lib/markdown/createRequestSchema.js

@@ -28,8 +28,8 @@ function mergeAllOf(allOf) {
             "x-examples": function () {
                 return true;
             },
-            ignoreAdditionalProperties: true,
         },
+        ignoreAdditionalProperties: true,
     });
     const required = allOf.reduce((acc, cur) => {
         if (Array.isArray(cur.required)) {
@@ -480,6 +480,7 @@ function createEdges({ name, schema, required, discriminator, }) {
             collapsible: false,
             name,
             required: Array.isArray(required) ? required.includes(name) : required,
+            deprecated: mergedSchemas.deprecated,
             schemaDescription: mergedSchemas.description,
             schemaName: schemaName,
             qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
@@ -507,6 +508,7 @@ function createEdges({ name, schema, required, discriminator, }) {
         collapsible: false,
         name,
         required: Array.isArray(required) ? required.includes(name) : required,
+        deprecated: schema.deprecated,
         schemaDescription: schema.description,
         schemaName: schemaName,
         qualifierMessage: (0, schema_1.getQualifierMessage)(schema),

package/lib/markdown/createResponseSchema.js

@@ -479,6 +479,7 @@ function createEdges({ name, schema, required, discriminator, }) {
             collapsible: false,
             name,
             required: false,
+            deprecated: mergedSchemas.deprecated,
             schemaDescription: mergedSchemas.description,
             schemaName: schemaName,
             qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
@@ -506,6 +507,7 @@ function createEdges({ name, schema, required, discriminator, }) {
         collapsible: false,
         name,
         required: false,
+        deprecated: schema.deprecated,
         schemaDescription: schema.description,
         schemaName: schemaName,
         qualifierMessage: (0, schema_1.getQualifierMessage)(schema),

package/lib/markdown/index.js

@@ -26,7 +26,7 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import MimeTabs from "@theme/MimeTabs";\n`,
         `import ParamsItem from "@theme/ParamsItem";\n`,
         `import ResponseSamples from "@theme/ResponseSamples";\n`,
-        `import SchemaItem from "@theme/SchemaItem"\n`,
+        `import SchemaItem from "@theme/SchemaItem";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,

package/lib/markdown/utils.d.ts

@@ -7,3 +7,4 @@ export declare function guard<T>(value: T | undefined, cb: (value: T) => Childre
 export declare function render(children: Children): string;
 export declare const lessThan: RegExp;
 export declare const greaterThan: RegExp;
+export declare const codeFence: RegExp;

package/lib/markdown/utils.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
+exports.codeFence = exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
 function create(tag, props) {
     const { children, ...rest } = props;
     let propString = "";
@@ -35,5 +35,6 @@ function render(children) {
 }
 exports.render = render;
 // Regex to selectively URL-encode '>' and '<' chars
-exports.lessThan = /<(?!(=|button|\s?\/button|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|a|\s?\/a|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|div|\s?\/div|center|\s?\/center))/giu;
-exports.greaterThan = /(?<!(button|details|summary|hr|br|span|strong|small|table|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|a|tag|li|ol|ul|img|div|center|\/|\s|"|'))>?!=/giu;
+exports.lessThan = /<(?!(=|button|\s?\/button|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|a|\s?\/a|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|div|\s?\/div|center|\s?\/center))/gu;
+exports.greaterThan = /(?<!(button|details|summary|hr|br|span|strong|small|table|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|a|tag|li|ol|ul|img|div|center|\/|\s|"|'))>/gu;
+exports.codeFence = /`{1,3}[\s\S]*?`{1,3}/g;

package/lib/openapi/createRequestExample.js

@@ -76,7 +76,7 @@ const sampleRequestFromSchema = (schema = {}) => {
             const { mergedSchemas } = (0, createRequestSchema_1.mergeAllOf)(allOf);
             if (mergedSchemas.properties) {
                 for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-                    if (value.readOnly && value.readOnly === true) {
+                    if ((value.readOnly && value.readOnly === true) || value.deprecated) {
                         delete mergedSchemas.properties[key];
                     }
                 }
@@ -99,14 +99,16 @@ const sampleRequestFromSchema = (schema = {}) => {
             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) {
+                        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) {
+                        if ((value.readOnly && value.readOnly === true) ||
+                            value.deprecated) {
                             delete prop.items.properties[key];
                         }
                     }
@@ -137,7 +139,7 @@ const sampleRequestFromSchema = (schema = {}) => {
             }
             return normalizeArray(schema.enum)[0];
         }
-        if (schema.readOnly && schema.readOnly === true) {
+        if ((schema.readOnly && schema.readOnly === true) || schema.deprecated) {
             return undefined;
         }
         return primitive(schema);

package/lib/openapi/createResponseExample.js

@@ -68,7 +68,8 @@ const sampleResponseFromSchema = (schema = {}) => {
             const { mergedSchemas } = (0, createResponseSchema_1.mergeAllOf)(allOf);
             if (mergedSchemas.properties) {
                 for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-                    if (value.writeOnly && value.writeOnly === true) {
+                    if ((value.writeOnly && value.writeOnly === true) ||
+                        value.deprecated) {
                         delete mergedSchemas.properties[key];
                     }
                 }
@@ -99,14 +100,16 @@ const sampleResponseFromSchema = (schema = {}) => {
             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) {
+                        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) {
+                        if ((value.writeOnly && value.writeOnly === true) ||
+                            value.deprecated) {
                             delete prop.items.properties[key];
                         }
                     }
@@ -137,7 +140,7 @@ const sampleResponseFromSchema = (schema = {}) => {
             }
             return normalizeArray(schema.enum)[0];
         }
-        if (schema.writeOnly && schema.writeOnly === true) {
+        if ((schema.writeOnly && schema.writeOnly === true) || schema.deprecated) {
             return undefined;
         }
         return primitive(schema);

package/lib/openapi/openapi.d.ts

@@ -5,8 +5,8 @@ interface OpenApiFiles {
     sourceDirName: string;
     data: OpenApiObject;
 }
-export declare function readOpenapiFiles(openapiPath: string, options: APIOptions): Promise<OpenApiFiles[]>;
-export declare function processOpenapiFiles(files: OpenApiFiles[], sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[][]]>;
-export declare function processOpenapiFile(openapiData: OpenApiObject, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[]]>;
+export declare function readOpenapiFiles(openapiPath: string): Promise<OpenApiFiles[]>;
+export declare function processOpenapiFiles(files: OpenApiFiles[], options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[][]]>;
+export declare function processOpenapiFile(openapiData: OpenApiObject, options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[]]>;
 export declare function getTagDisplayName(tagName: string, tags: TagObject[]): string;
 export {};

package/lib/openapi/openapi.js

@@ -60,11 +60,12 @@ async function createPostmanCollection(openapiData) {
     }
     return await jsonToCollection(data);
 }
-function createItems(openapiData, sidebarOptions) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+function createItems(openapiData, options, sidebarOptions) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2;
     // TODO: Find a better way to handle this
     let items = [];
-    const infoId = (0, kebabCase_1.default)(openapiData.info.title);
+    const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
+    const infoId = (0, kebabCase_1.default)(infoIdSpaces);
     if (openapiData.info.description) {
         // Only create an info page if we have a description.
         const infoDescription = (_a = openapiData.info) === null || _a === void 0 ? void 0 : _a.description;
@@ -171,6 +172,98 @@ function createItems(openapiData, sidebarOptions) {
                             .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                             .replace(/\s+$/, "")
                         : "",
+                    ...((options === null || options === void 0 ? void 0 : options.proxy) && { proxy: options.proxy }),
+                },
+                api: {
+                    ...defaults,
+                    tags: operationObject.tags,
+                    method,
+                    path,
+                    servers,
+                    security,
+                    securitySchemes,
+                    jsonRequestBodyExample,
+                    info: openapiData.info,
+                },
+            };
+            items.push(apiPage);
+        }
+    }
+    // Gather x-webhooks endpoints
+    for (let [path, pathObject] of Object.entries((_q = openapiData["x-webhooks"]) !== null && _q !== void 0 ? _q : {})) {
+        path = "webhook";
+        const { $ref, description, parameters, servers, summary, ...rest } = pathObject;
+        for (let [method, operationObject] of Object.entries({ ...rest })) {
+            method = "event";
+            const title = (_s = (_r = operationObject.summary) !== null && _r !== void 0 ? _r : operationObject.operationId) !== null && _s !== void 0 ? _s : "Missing summary";
+            if (operationObject.description === undefined) {
+                operationObject.description =
+                    (_u = (_t = operationObject.summary) !== null && _t !== void 0 ? _t : operationObject.operationId) !== null && _u !== void 0 ? _u : "";
+            }
+            const baseId = operationObject.operationId
+                ? (0, kebabCase_1.default)(operationObject.operationId)
+                : (0, kebabCase_1.default)(operationObject.summary);
+            const servers = (_w = (_v = operationObject.servers) !== null && _v !== void 0 ? _v : pathObject.servers) !== null && _w !== void 0 ? _w : openapiData.servers;
+            const security = (_x = operationObject.security) !== null && _x !== void 0 ? _x : openapiData.security;
+            // Add security schemes so we know how to handle security.
+            const securitySchemes = (_y = openapiData.components) === null || _y === void 0 ? void 0 : _y.securitySchemes;
+            // Make sure schemes are lowercase. See: https://github.com/cloud-annotations/docusaurus-plugin-openapi/issues/79
+            if (securitySchemes) {
+                for (let securityScheme of Object.values(securitySchemes)) {
+                    if (securityScheme.type === "http") {
+                        securityScheme.scheme = securityScheme.scheme.toLowerCase();
+                    }
+                }
+            }
+            let jsonRequestBodyExample;
+            const body = (_0 = (_z = operationObject.requestBody) === null || _z === void 0 ? void 0 : _z.content) === null || _0 === void 0 ? void 0 : _0["application/json"];
+            if (body === null || body === void 0 ? void 0 : body.schema) {
+                jsonRequestBodyExample = (0, createRequestExample_1.sampleRequestFromSchema)(body.schema);
+            }
+            // Handle vendor JSON media types
+            const bodyContent = (_1 = operationObject.requestBody) === null || _1 === void 0 ? void 0 : _1.content;
+            if (bodyContent) {
+                const firstBodyContentKey = Object.keys(bodyContent)[0];
+                if (firstBodyContentKey.endsWith("+json")) {
+                    const firstBody = bodyContent[firstBodyContentKey];
+                    if (firstBody === null || firstBody === void 0 ? void 0 : firstBody.schema) {
+                        jsonRequestBodyExample = (0, createRequestExample_1.sampleRequestFromSchema)(firstBody.schema);
+                    }
+                }
+            }
+            // TODO: Don't include summary temporarilly
+            const { summary, ...defaults } = operationObject;
+            // Merge common parameters with operation parameters
+            // Operation params take precendence over common params
+            if (parameters !== undefined) {
+                if (operationObject.parameters !== undefined) {
+                    defaults.parameters = (0, unionBy_1.default)(operationObject.parameters, parameters, "name");
+                }
+                else {
+                    defaults.parameters = parameters;
+                }
+            }
+            const opDescription = operationObject.description;
+            let splitDescription;
+            if (opDescription) {
+                splitDescription = opDescription.match(/[^\r\n]+/g);
+            }
+            const apiPage = {
+                type: "api",
+                id: baseId,
+                infoId: infoId !== null && infoId !== void 0 ? infoId : "",
+                unversionedId: baseId,
+                title: title ? title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'") : "",
+                description: operationObject.description
+                    ? operationObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                    : "",
+                frontMatter: {
+                    description: splitDescription
+                        ? splitDescription[0]
+                            .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                            .replace(/\s+$/, "")
+                        : "",
+                    ...((options === null || options === void 0 ? void 0 : options.proxy) && { proxy: options.proxy }),
                 },
                 api: {
                     ...defaults,
@@ -189,7 +282,7 @@ function createItems(openapiData, sidebarOptions) {
     }
     if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
         // Get global tags
-        const tags = (_q = openapiData.tags) !== null && _q !== void 0 ? _q : [];
+        const tags = (_2 = openapiData.tags) !== null && _2 !== void 0 ? _2 : [];
         // Get operation tags
         const apiItems = items.filter((item) => {
             return item.type === "api";
@@ -248,7 +341,7 @@ function bindCollectionToApiItems(items, postmanCollection) {
         }
     });
 }
-async function readOpenapiFiles(openapiPath, options) {
+async function readOpenapiFiles(openapiPath) {
     if (!(0, index_1.isURL)(openapiPath)) {
         const stat = await fs_extra_1.default.lstat(openapiPath);
         if (stat.isDirectory()) {
@@ -281,10 +374,10 @@ async function readOpenapiFiles(openapiPath, options) {
     ];
 }
 exports.readOpenapiFiles = readOpenapiFiles;
-async function processOpenapiFiles(files, sidebarOptions) {
+async function processOpenapiFiles(files, options, sidebarOptions) {
     const promises = files.map(async (file) => {
         if (file.data !== undefined) {
-            const processedFile = await processOpenapiFile(file.data, sidebarOptions);
+            const processedFile = await processOpenapiFile(file.data, options, sidebarOptions);
             const itemsObjectsArray = processedFile[0].map((item) => ({
                 ...item,
             }));
@@ -315,9 +408,9 @@ async function processOpenapiFiles(files, sidebarOptions) {
     return [items, tags];
 }
 exports.processOpenapiFiles = processOpenapiFiles;
-async function processOpenapiFile(openapiData, sidebarOptions) {
+async function processOpenapiFile(openapiData, options, sidebarOptions) {
     const postmanCollection = await createPostmanCollection(openapiData);
-    const items = createItems(openapiData, sidebarOptions);
+    const items = createItems(openapiData, options, sidebarOptions);
     bindCollectionToApiItems(items, postmanCollection);
     let tags = [];
     if (openapiData.tags !== undefined) {

package/lib/openapi/openapi.test.js

@@ -16,7 +16,7 @@ const _1 = require(".");
 describe("openapi", () => {
     describe("readOpenapiFiles", () => {
         it("readOpenapiFiles", async () => {
-            const results = await (0, _1.readOpenapiFiles)((0, utils_1.posixPath)(path_1.default.join(__dirname, "__fixtures__/examples")), { specPath: "./", outputDir: "./" });
+            const results = await (0, _1.readOpenapiFiles)((0, utils_1.posixPath)(path_1.default.join(__dirname, "__fixtures__/examples")));
             const categoryMeta = results.find((x) => x.source.endsWith("_category_.json"));
             expect(categoryMeta).toBeFalsy();
             // console.log(results);

package/lib/openapi/types.d.ts

@@ -12,6 +12,7 @@ export interface OpenApiObject {
     tags?: TagObject[];
     externalDocs?: ExternalDocumentationObject;
     swagger?: string;
+    "x-webhooks"?: PathsObject;
 }
 export interface OpenApiObjectWithRef {
     openapi: string;

package/lib/openapi/utils/loadAndResolveSpec.js

@@ -10,7 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadAndResolveSpec = exports.convertSwagger2OpenAPI = void 0;
-const json_schema_ref_parser_1 = __importDefault(require("@apidevtools/json-schema-ref-parser"));
+const json_schema_ref_parser_1 = __importDefault(require("@paloaltonetworks/json-schema-ref-parser"));
 const openapi_core_1 = require("@redocly/openapi-core");
 const chalk_1 = __importDefault(require("chalk"));
 // @ts-ignore
@@ -58,7 +58,13 @@ function serializer(replacer, cycleReplacer) {
 }
 function convertSwagger2OpenAPI(spec) {
     console.warn("[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0");
-    return new Promise((resolve, reject) => (0, swagger2openapi_1.convertObj)(spec, { patch: true, warnOnly: true, text: "{}", anchors: true }, (err, res) => {
+    return new Promise((resolve, reject) => (0, swagger2openapi_1.convertObj)(spec, {
+        patch: true,
+        warnOnly: true,
+        text: "{}",
+        anchors: true,
+        resolveInternal: true,
+    }, (err, res) => {
         // TODO: log any warnings
         if (err) {
             return reject(err);

package/lib/options.js

@@ -21,6 +21,7 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
     config: utils_validation_1.Joi.object()
         .pattern(/^/, utils_validation_1.Joi.object({
         specPath: utils_validation_1.Joi.string().required(),
+        proxy: utils_validation_1.Joi.string(),
         outputDir: utils_validation_1.Joi.string().required(),
         template: utils_validation_1.Joi.string(),
         downloadUrl: utils_validation_1.Joi.string(),

package/lib/types.d.ts

@@ -20,6 +20,7 @@ export interface APIOptions {
     versions?: {
         [key: string]: APIVersionOptions;
     };
+    proxy?: string;
 }
 export interface SidebarOptions {
     groupPathsBy?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.4.7",
+  "version": "1.5.1-hotfix1",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -39,7 +39,7 @@
     "utility-types": "^3.10.0"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^9.0.9",
+    "@paloaltonetworks/json-schema-ref-parser": "0.0.0-dev-hotfix1",
     "@docusaurus/mdx-loader": "^2.0.1",
     "@docusaurus/plugin-content-docs": "^2.0.1",
     "@docusaurus/utils": "^2.0.1",
@@ -67,6 +67,5 @@
   },
   "engines": {
     "node": ">=14"
-  },
-  "gitHead": "c4908dd9886556981677c8ff900450252abe6bf3"
+  }
 }

package/src/index.ts

@@ -106,9 +106,10 @@ export default function pluginOpenAPIDocs(
       : path.resolve(siteDir, specPath);
 
     try {
-      const openapiFiles = await readOpenapiFiles(contentPath, options);
+      const openapiFiles = await readOpenapiFiles(contentPath);
       const [loadedApi, tags] = await processOpenapiFiles(
         openapiFiles,
+        options,
         sidebarOptions!
       );
       if (!fs.existsSync(outputDir)) {
@@ -182,6 +183,10 @@ sidebar_class_name: "{{{api.method}}} api-method"
 {{#infoPath}}
 info_path: {{{infoPath}}}
 {{/infoPath}}
+custom_edit_url: null
+{{#frontMatter.proxy}}
+proxy: {{{frontMatter.proxy}}}
+{{/frontMatter.proxy}}
 ---
 
 {{{markdown}}}

package/src/markdown/createDescription.ts

@@ -5,13 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { greaterThan, lessThan } from "./utils";
+import { greaterThan, codeFence } from "./utils";
 
 export function createDescription(description: string | undefined) {
   if (!description) {
     return "";
   }
   return `\n\n${description
-    .replace(lessThan, "<")
-    .replace(greaterThan, ">")}\n\n`;
+    .replace(greaterThan, "\\>")
+    .replace(codeFence, function (match) {
+      return match.replace(/\\>/g, ">");
+    })}\n\n`;
 }

package/src/markdown/createRequestSchema.ts

@@ -29,8 +29,8 @@ export function mergeAllOf(allOf: SchemaObject[]) {
       "x-examples": function () {
         return true;
       },
-      ignoreAdditionalProperties: true,
     },
+    ignoreAdditionalProperties: true,
   });
 
   const required = allOf.reduce((acc, cur) => {
@@ -597,6 +597,7 @@ function createEdges({
       collapsible: false,
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
+      deprecated: mergedSchemas.deprecated,
       schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
@@ -630,6 +631,7 @@ function createEdges({
     collapsible: false,
     name,
     required: Array.isArray(required) ? required.includes(name) : required,
+    deprecated: schema.deprecated,
     schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),

package/src/markdown/createResponseSchema.ts

@@ -597,6 +597,7 @@ function createEdges({
       collapsible: false,
       name,
       required: false,
+      deprecated: mergedSchemas.deprecated,
       schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
@@ -630,6 +631,7 @@ function createEdges({
     collapsible: false,
     name,
     required: false,
+    deprecated: schema.deprecated,
     schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),

package/src/markdown/index.ts

@@ -53,7 +53,7 @@ export function createApiPageMD({
     `import MimeTabs from "@theme/MimeTabs";\n`,
     `import ParamsItem from "@theme/ParamsItem";\n`,
     `import ResponseSamples from "@theme/ResponseSamples";\n`,
-    `import SchemaItem from "@theme/SchemaItem"\n`,
+    `import SchemaItem from "@theme/SchemaItem";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
     `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,

package/src/markdown/utils.ts

@@ -43,6 +43,7 @@ export function render(children: Children): string {
 
 // Regex to selectively URL-encode '>' and '<' chars
 export const lessThan =
-  /<(?!(=|button|\s?\/button|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|a|\s?\/a|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|div|\s?\/div|center|\s?\/center))/giu;
+  /<(?!(=|button|\s?\/button|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|a|\s?\/a|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|div|\s?\/div|center|\s?\/center))/gu;
 export const greaterThan =
-  /(?<!(button|details|summary|hr|br|span|strong|small|table|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|a|tag|li|ol|ul|img|div|center|\/|\s|"|'))>?!=/giu;
+  /(?<!(button|details|summary|hr|br|span|strong|small|table|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|a|tag|li|ol|ul|img|div|center|\/|\s|"|'))>/gu;
+export const codeFence = /`{1,3}[\s\S]*?`{1,3}/g;

package/src/openapi/createRequestExample.ts

@@ -98,7 +98,7 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
         mergeAllOf(allOf);
       if (mergedSchemas.properties) {
         for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-          if (value.readOnly && value.readOnly === true) {
+          if ((value.readOnly && value.readOnly === true) || value.deprecated) {
             delete mergedSchemas.properties[key];
           }
         }
@@ -121,7 +121,10 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
       for (let [name, prop] of Object.entries(properties ?? {})) {
         if (prop.properties) {
           for (const [key, value] of Object.entries(prop.properties)) {
-            if (value.readOnly && value.readOnly === true) {
+            if (
+              (value.readOnly && value.readOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.properties[key];
             }
           }
@@ -129,7 +132,10 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
 
         if (prop.items && prop.items.properties) {
           for (const [key, value] of Object.entries(prop.items.properties)) {
-            if (value.readOnly && value.readOnly === true) {
+            if (
+              (value.readOnly && value.readOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.items.properties[key];
             }
           }
@@ -168,7 +174,7 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
       return normalizeArray(schema.enum)[0];
     }
 
-    if (schema.readOnly && schema.readOnly === true) {
+    if ((schema.readOnly && schema.readOnly === true) || schema.deprecated) {
       return undefined;
     }
 

package/src/openapi/createResponseExample.ts

@@ -88,7 +88,10 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
         mergeAllOf(allOf);
       if (mergedSchemas.properties) {
         for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-          if (value.writeOnly && value.writeOnly === true) {
+          if (
+            (value.writeOnly && value.writeOnly === true) ||
+            value.deprecated
+          ) {
             delete mergedSchemas.properties[key];
           }
         }
@@ -121,7 +124,10 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
       for (let [name, prop] of Object.entries(properties ?? {})) {
         if (prop.properties) {
           for (const [key, value] of Object.entries(prop.properties)) {
-            if (value.writeOnly && value.writeOnly === true) {
+            if (
+              (value.writeOnly && value.writeOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.properties[key];
             }
           }
@@ -129,7 +135,10 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
 
         if (prop.items && prop.items.properties) {
           for (const [key, value] of Object.entries(prop.items.properties)) {
-            if (value.writeOnly && value.writeOnly === true) {
+            if (
+              (value.writeOnly && value.writeOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.items.properties[key];
             }
           }
@@ -168,7 +177,7 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
       return normalizeArray(schema.enum)[0];
     }
 
-    if (schema.writeOnly && schema.writeOnly === true) {
+    if ((schema.writeOnly && schema.writeOnly === true) || schema.deprecated) {
       return undefined;
     }
 

package/src/openapi/openapi.test.ts

@@ -17,8 +17,7 @@ describe("openapi", () => {
   describe("readOpenapiFiles", () => {
     it("readOpenapiFiles", async () => {
       const results = await readOpenapiFiles(
-        posixPath(path.join(__dirname, "__fixtures__/examples")),
-        { specPath: "./", outputDir: "./" }
+        posixPath(path.join(__dirname, "__fixtures__/examples"))
       );
       const categoryMeta = results.find((x) =>
         x.source.endsWith("_category_.json")

package/src/openapi/openapi.ts

@@ -80,11 +80,13 @@ type PartialPage<T> = Omit<T, "permalink" | "source" | "sourceDirName">;
 
 function createItems(
   openapiData: OpenApiObject,
+  options: APIOptions,
   sidebarOptions: SidebarOptions
 ): ApiMetadata[] {
   // TODO: Find a better way to handle this
   let items: PartialPage<ApiMetadata>[] = [];
-  const infoId = kebabCase(openapiData.info.title);
+  const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
+  const infoId = kebabCase(infoIdSpaces);
 
   if (openapiData.info.description) {
     // Only create an info page if we have a description.
@@ -218,6 +220,7 @@ function createItems(
                 .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                 .replace(/\s+$/, "")
             : "",
+          ...(options?.proxy && { proxy: options.proxy }),
         },
         api: {
           ...defaults,
@@ -236,6 +239,122 @@ function createItems(
     }
   }
 
+  // Gather x-webhooks endpoints
+  for (let [path, pathObject] of Object.entries(
+    openapiData["x-webhooks"] ?? {}
+  )) {
+    path = "webhook";
+    const { $ref, description, parameters, servers, summary, ...rest } =
+      pathObject;
+    for (let [method, operationObject] of Object.entries({ ...rest })) {
+      method = "event";
+      const title =
+        operationObject.summary ??
+        operationObject.operationId ??
+        "Missing summary";
+      if (operationObject.description === undefined) {
+        operationObject.description =
+          operationObject.summary ?? operationObject.operationId ?? "";
+      }
+
+      const baseId = operationObject.operationId
+        ? kebabCase(operationObject.operationId)
+        : kebabCase(operationObject.summary);
+
+      const servers =
+        operationObject.servers ?? pathObject.servers ?? openapiData.servers;
+
+      const security = operationObject.security ?? openapiData.security;
+
+      // Add security schemes so we know how to handle security.
+      const securitySchemes = openapiData.components?.securitySchemes;
+
+      // Make sure schemes are lowercase. See: https://github.com/cloud-annotations/docusaurus-plugin-openapi/issues/79
+      if (securitySchemes) {
+        for (let securityScheme of Object.values(securitySchemes)) {
+          if (securityScheme.type === "http") {
+            securityScheme.scheme = securityScheme.scheme.toLowerCase();
+          }
+        }
+      }
+
+      let jsonRequestBodyExample;
+      const body = operationObject.requestBody?.content?.["application/json"];
+      if (body?.schema) {
+        jsonRequestBodyExample = sampleRequestFromSchema(body.schema);
+      }
+
+      // Handle vendor JSON media types
+      const bodyContent = operationObject.requestBody?.content;
+      if (bodyContent) {
+        const firstBodyContentKey = Object.keys(bodyContent)[0];
+        if (firstBodyContentKey.endsWith("+json")) {
+          const firstBody = bodyContent[firstBodyContentKey];
+          if (firstBody?.schema) {
+            jsonRequestBodyExample = sampleRequestFromSchema(firstBody.schema);
+          }
+        }
+      }
+
+      // TODO: Don't include summary temporarilly
+      const { summary, ...defaults } = operationObject;
+
+      // Merge common parameters with operation parameters
+      // Operation params take precendence over common params
+      if (parameters !== undefined) {
+        if (operationObject.parameters !== undefined) {
+          defaults.parameters = unionBy(
+            operationObject.parameters,
+            parameters,
+            "name"
+          );
+        } else {
+          defaults.parameters = parameters;
+        }
+      }
+
+      const opDescription = operationObject.description;
+      let splitDescription: any;
+      if (opDescription) {
+        splitDescription = opDescription.match(/[^\r\n]+/g);
+      }
+
+      const apiPage: PartialPage<ApiPageMetadata> = {
+        type: "api",
+        id: baseId,
+        infoId: infoId ?? "",
+        unversionedId: baseId,
+        title: title ? title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'") : "",
+        description: operationObject.description
+          ? operationObject.description.replace(
+              /((?:^|[^\\])(?:\\{2})*)"/g,
+              "$1'"
+            )
+          : "",
+        frontMatter: {
+          description: splitDescription
+            ? splitDescription[0]
+                .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                .replace(/\s+$/, "")
+            : "",
+          ...(options?.proxy && { proxy: options.proxy }),
+        },
+        api: {
+          ...defaults,
+          tags: operationObject.tags,
+          method,
+          path,
+          servers,
+          security,
+          securitySchemes,
+          jsonRequestBodyExample,
+          info: openapiData.info,
+        },
+      };
+      items.push(apiPage);
+    }
+  }
+
   if (sidebarOptions?.categoryLinkSource === "tag") {
     // Get global tags
     const tags: TagObject[] = openapiData.tags ?? [];
@@ -318,8 +437,7 @@ interface OpenApiFiles {
 }
 
 export async function readOpenapiFiles(
-  openapiPath: string,
-  options: APIOptions
+  openapiPath: string
 ): Promise<OpenApiFiles[]> {
   if (!isURL(openapiPath)) {
     const stat = await fs.lstat(openapiPath);
@@ -361,11 +479,16 @@ export async function readOpenapiFiles(
 
 export async function processOpenapiFiles(
   files: OpenApiFiles[],
+  options: APIOptions,
   sidebarOptions: SidebarOptions
 ): Promise<[ApiMetadata[], TagObject[][]]> {
   const promises = files.map(async (file) => {
     if (file.data !== undefined) {
-      const processedFile = await processOpenapiFile(file.data, sidebarOptions);
+      const processedFile = await processOpenapiFile(
+        file.data,
+        options,
+        sidebarOptions
+      );
       const itemsObjectsArray = processedFile[0].map((item) => ({
         ...item,
       }));
@@ -402,10 +525,11 @@ export async function processOpenapiFiles(
 
 export async function processOpenapiFile(
   openapiData: OpenApiObject,
+  options: APIOptions,
   sidebarOptions: SidebarOptions
 ): Promise<[ApiMetadata[], TagObject[]]> {
   const postmanCollection = await createPostmanCollection(openapiData);
-  const items = createItems(openapiData, sidebarOptions);
+  const items = createItems(openapiData, options, sidebarOptions);
 
   bindCollectionToApiItems(items, postmanCollection);
 

package/src/openapi/types.ts

@@ -21,6 +21,7 @@ export interface OpenApiObject {
   tags?: TagObject[];
   externalDocs?: ExternalDocumentationObject;
   swagger?: string;
+  "x-webhooks"?: PathsObject;
 }
 
 export interface OpenApiObjectWithRef {

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import $RefParser from "@apidevtools/json-schema-ref-parser";
+import $RefParser from "@paloaltonetworks/json-schema-ref-parser";
 import { bundle, Config } from "@redocly/openapi-core";
 import type { Source, Document } from "@redocly/openapi-core";
 import { ResolvedConfig } from "@redocly/openapi-core/lib/config";
@@ -66,7 +66,13 @@ export function convertSwagger2OpenAPI(spec: object) {
   return new Promise((resolve, reject) =>
     convertObj(
       spec,
-      { patch: true, warnOnly: true, text: "{}", anchors: true },
+      {
+        patch: true,
+        warnOnly: true,
+        text: "{}",
+        anchors: true,
+        resolveInternal: true,
+      },
       (err: any, res: any) => {
         // TODO: log any warnings
         if (err) {

package/src/options.ts

@@ -23,6 +23,7 @@ export const OptionsSchema = Joi.object({
       /^/,
       Joi.object({
         specPath: Joi.string().required(),
+        proxy: Joi.string(),
         outputDir: Joi.string().required(),
         template: Joi.string(),
         downloadUrl: Joi.string(),

package/src/types.ts

@@ -40,6 +40,7 @@ export interface APIOptions {
   versions?: {
     [key: string]: APIVersionOptions;
   };
+  proxy?: string;
 }
 
 export interface SidebarOptions {

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Palo Alto Networks
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.