docusaurus-plugin-openapi-docs 1.5.0 → 1.5.1

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

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/openapi.js

@@ -61,7 +61,7 @@ async function createPostmanCollection(openapiData) {
     return await jsonToCollection(data);
 }
 function createItems(openapiData, options, sidebarOptions) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    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 infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
@@ -189,9 +189,100 @@ function createItems(openapiData, options, sidebarOptions) {
             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,
+                    tags: operationObject.tags,
+                    method,
+                    path,
+                    servers,
+                    security,
+                    securitySchemes,
+                    jsonRequestBodyExample,
+                    info: openapiData.info,
+                },
+            };
+            items.push(apiPage);
+        }
+    }
     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";

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

@@ -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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "7ed68875703f5481aaf58f936ce58feea36e6596"
+  "gitHead": "11d2c2fdb2bc81048097b05bc65698777d54e456"
 }

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) => {

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/openapi.ts

@@ -239,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 ?? [];

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

@@ -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) {