docusaurus-plugin-openapi-docs 0.0.0-531 → 0.0.0-533

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

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-531",
+  "version": "0.0.0-533",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "97da2ed70f7bb1d712b85fad818fbed77e611aa0"
+  "gitHead": "ca4229525685eed0dcf9c886d4f0d3ec510e175b"
 }

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 {