@camunda8/docusaurus-theme-openapi-docs 4.5.1

package/src/theme/ApiExplorer/Authorization/slice.ts

@@ -0,0 +1,146 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { createSlice, PayloadAction } from "@reduxjs/toolkit";
+import { createStorage, hashArray } from "@theme/ApiExplorer/storage-utils";
+import {
+  SecurityRequirementObject,
+  SecuritySchemeObject,
+} from "@camunda8/docusaurus-plugin-openapi-docs/src/openapi/types";
+/* eslint-disable import/no-extraneous-dependencies*/
+import { ThemeConfig } from "@camunda8/docusaurus-theme-openapi-docs/src/types";
+
+import { getAuthDataKeys } from "./auth-types";
+
+// The global definitions
+// "securitySchemes": {
+//   "BearerAuth": { "type": "http", "scheme": "BeAreR" },
+//   "BasicAuth": { "type": "http", "scheme": "basic" }
+// },
+
+// The operation level requirements
+// "security": [
+//   { "BearerAuth": [] },
+//   { "BearerAuth": [], "BasicAuth": [] }
+// ],
+
+// SLICE_STATE
+// data:
+//   BearerAuth:
+//     token=xxx
+//   BasicAuth:
+//     username=xxx
+//     password=xxx
+//
+// options:
+//    "BearerAuth": [{ key: "BearerAuth", scopes: [], ...rest }]
+//    "BearerAuth and BasicAuth": [{ key: "BearerAuth", scopes: [], ...rest }, { key: "BasicAuth", scopes: [], ...rest }]
+//
+// selected: "BearerAuth and BasicAuth"
+
+// LOCAL_STORAGE
+// hash(SLICE_STATE.options) -> "BearerAuth and BasicAuth"
+// BearerAuth                -> { token: xxx }
+// BasicAuth                 -> { username: xxx, password: xxx }
+
+export function createAuth({
+  security,
+  securitySchemes,
+  options: opts,
+}: {
+  security?: SecurityRequirementObject[];
+  securitySchemes?: {
+    [key: string]: SecuritySchemeObject;
+  };
+  options?: ThemeConfig["api"];
+}): AuthState {
+  const storage = createStorage("sessionStorage");
+
+  let data: AuthState["data"] = {};
+  let options: AuthState["options"] = {};
+
+  for (const option of security ?? []) {
+    const id = Object.keys(option).join(" and ");
+    for (const [schemeID, scopes] of Object.entries(option)) {
+      const scheme = securitySchemes?.[schemeID];
+      if (scheme) {
+        if (options[id] === undefined) {
+          options[id] = [];
+        }
+        const dataKeys = getAuthDataKeys(scheme);
+        for (const key of dataKeys) {
+          if (data[schemeID] === undefined) {
+            data[schemeID] = {};
+          }
+
+          let persisted = undefined;
+          try {
+            persisted = JSON.parse(storage.getItem(schemeID) ?? "")[key];
+          } catch {}
+
+          data[schemeID][key] = persisted;
+        }
+        options[id].push({
+          ...scheme,
+          key: schemeID,
+          scopes,
+        });
+      }
+    }
+  }
+
+  let persisted = undefined;
+  try {
+    persisted = storage.getItem(hashArray(Object.keys(options))) ?? undefined;
+  } catch {}
+
+  return {
+    data,
+    options,
+    selected: persisted ?? Object.keys(options)[0],
+  };
+}
+
+export type Scheme = {
+  key: string;
+  scopes: string[];
+} & SecuritySchemeObject;
+
+export interface AuthState {
+  data: {
+    [scheme: string]: {
+      [key: string]: string | undefined;
+    };
+  };
+  options: {
+    [key: string]: Scheme[];
+  };
+  selected?: string;
+}
+
+const initialState: AuthState = {} as any;
+
+export const slice = createSlice({
+  name: "auth",
+  initialState,
+  reducers: {
+    setAuthData: (
+      state,
+      action: PayloadAction<{ scheme: string; key: string; value?: string }>
+    ) => {
+      const { scheme, key, value } = action.payload;
+      state.data[scheme][key] = value;
+    },
+    setSelectedAuth: (state, action: PayloadAction<string>) => {
+      state.selected = action.payload;
+    },
+  },
+});
+
+export const { setAuthData, setSelectedAuth } = slice.actions;
+
+export default slice.reducer;

package/src/theme/ApiExplorer/Body/index.tsx

@@ -0,0 +1,388 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import React from "react";
+
+import { translate } from "@docusaurus/Translate";
+
+import json2xml from "@theme/ApiExplorer/Body/json2xml";
+import FormFileUpload from "@theme/ApiExplorer/FormFileUpload";
+import FormItem from "@theme/ApiExplorer/FormItem";
+import FormSelect from "@theme/ApiExplorer/FormSelect";
+import FormTextInput from "@theme/ApiExplorer/FormTextInput";
+import LiveApp from "@theme/ApiExplorer/LiveEditor";
+import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
+import Markdown from "@theme/Markdown";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
+import { OPENAPI_BODY, OPENAPI_REQUEST } from "@theme/translationIds";
+import { RequestBodyObject } from "@camunda8/docusaurus-plugin-openapi-docs/src/openapi/types";
+import format from "xml-formatter";
+
+import {
+  clearFormBodyKey,
+  clearRawBody,
+  setFileFormBody,
+  setFileRawBody,
+  setStringFormBody,
+} from "./slice";
+
+export interface Props {
+  jsonRequestBodyExample: string;
+  requestBodyMetadata?: RequestBodyObject;
+  methods?: any;
+  required?: boolean;
+}
+
+function BodyWrap({
+  requestBodyMetadata,
+  jsonRequestBodyExample,
+  methods,
+  required,
+}: Props) {
+  const contentType = useTypedSelector((state: any) => state.contentType.value);
+
+  // NOTE: We used to check if body was required, but opted to always show the request body
+  // to reduce confusion, see: https://github.com/cloud-annotations/docusaurus-openapi/issues/145
+
+  // No body
+  if (contentType === undefined) {
+    return null;
+  }
+
+  return (
+    <Body
+      requestBodyMetadata={requestBodyMetadata}
+      jsonRequestBodyExample={jsonRequestBodyExample}
+      required={required}
+    />
+  );
+}
+
+function Body({
+  requestBodyMetadata,
+  jsonRequestBodyExample,
+  methods,
+  required,
+}: Props) {
+  const contentType = useTypedSelector((state: any) => state.contentType.value);
+  const dispatch = useTypedDispatch();
+
+  // Lot's of possible content-types:
+  // - application/json
+  // - application/xml
+  // - text/plain
+  // - text/css
+  // - text/html
+  // - text/javascript
+  // - application/javascript
+  // - multipart/form-data
+  // - application/x-www-form-urlencoded
+  // - image/svg+xml;charset=US-ASCII
+
+  // Show editor:
+  // - application/json
+  // - application/xml
+  // - */*
+
+  // Show form:
+  // - multipart/form-data
+  // - application/x-www-form-urlencoded
+
+  const schema = requestBodyMetadata?.content?.[contentType]?.schema;
+  const example = requestBodyMetadata?.content?.[contentType]?.example;
+  const examples = requestBodyMetadata?.content?.[contentType]?.examples;
+
+  if (schema?.format === "binary") {
+    return (
+      <FormItem>
+        <FormFileUpload
+          placeholder={
+            schema.description ||
+            translate({ id: OPENAPI_REQUEST.BODY_TITLE, message: "Body" })
+          }
+          onChange={(file: any) => {
+            if (file === undefined) {
+              dispatch(clearRawBody());
+              return;
+            }
+            dispatch(
+              setFileRawBody({
+                src: `/path/to/${file.name}`,
+                content: file,
+              })
+            );
+          }}
+        />
+      </FormItem>
+    );
+  }
+  if (
+    (contentType === "multipart/form-data" ||
+      contentType === "application/x-www-form-urlencoded") &&
+    schema?.type === "object"
+  ) {
+    return (
+      <FormItem className="openapi-explorer__form-item-body-container">
+        <div>
+          {Object.entries(schema.properties ?? {}).map(([key, val]: any) => {
+            if (val.format === "binary") {
+              return (
+                <FormItem
+                  key={key}
+                  label={key}
+                  required={
+                    Array.isArray(schema.required) &&
+                    schema.required.includes(key)
+                  }
+                >
+                  <FormFileUpload
+                    placeholder={val.description || key}
+                    onChange={(file: any) => {
+                      if (file === undefined) {
+                        dispatch(clearFormBodyKey(key));
+                        return;
+                      }
+                      dispatch(
+                        setFileFormBody({
+                          key: key,
+                          value: {
+                            src: `/path/to/${file.name}`,
+                            content: file,
+                          },
+                        })
+                      );
+                    }}
+                  />
+                </FormItem>
+              );
+            }
+
+            if (val.enum) {
+              return (
+                <FormItem
+                  key={key}
+                  label={key}
+                  required={
+                    Array.isArray(schema.required) &&
+                    schema.required.includes(key)
+                  }
+                >
+                  <FormSelect
+                    options={["---", ...val.enum]}
+                    onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
+                      const val = e.target.value;
+                      if (val === "---") {
+                        dispatch(clearFormBodyKey(key));
+                      } else {
+                        dispatch(
+                          setStringFormBody({
+                            key: key,
+                            value: val,
+                          })
+                        );
+                      }
+                    }}
+                  />
+                </FormItem>
+              );
+            }
+            // TODO: support all the other types.
+            return (
+              <FormItem
+                key={key}
+                label={key}
+                required={
+                  Array.isArray(schema.required) &&
+                  schema.required.includes(key)
+                }
+              >
+                <FormTextInput
+                  paramName={key}
+                  isRequired={
+                    Array.isArray(schema.required) &&
+                    schema.required.includes(key)
+                  }
+                  placeholder={val.description || key}
+                  onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+                    dispatch(
+                      setStringFormBody({ key: key, value: e.target.value })
+                    );
+                  }}
+                />
+              </FormItem>
+            );
+          })}
+        </div>
+      </FormItem>
+    );
+  }
+
+  let language = "plaintext";
+  let defaultBody = ""; //"body content";
+  let exampleBody;
+  let examplesBodies = [] as any;
+
+  if (
+    contentType.includes("application/json") ||
+    contentType.endsWith("+json")
+  ) {
+    if (jsonRequestBodyExample) {
+      defaultBody = JSON.stringify(jsonRequestBodyExample, null, 2);
+    }
+    if (example) {
+      exampleBody = JSON.stringify(example, null, 2);
+    }
+    if (examples) {
+      for (const [key, example] of Object.entries(examples)) {
+        let body = example.value;
+        try {
+          // If the value is already valid JSON we shouldn't double encode the value
+          JSON.parse(example.value);
+        } catch (e) {
+          body = JSON.stringify(example.value, null, 2);
+        }
+
+        examplesBodies.push({
+          label: key,
+          body,
+          summary: example.summary,
+        });
+      }
+    }
+    language = "json";
+  }
+
+  if (contentType === "application/xml" || contentType.endsWith("+xml")) {
+    if (jsonRequestBodyExample) {
+      try {
+        defaultBody = format(json2xml(jsonRequestBodyExample, ""), {
+          indentation: "  ",
+          lineSeparator: "\n",
+          collapseContent: true,
+        });
+      } catch {
+        defaultBody = json2xml(jsonRequestBodyExample);
+      }
+    }
+    if (example) {
+      try {
+        exampleBody = format(json2xml(example, ""), {
+          indentation: "  ",
+          lineSeparator: "\n",
+          collapseContent: true,
+        });
+      } catch {
+        exampleBody = json2xml(example);
+      }
+    }
+    if (examples) {
+      for (const [key, example] of Object.entries(examples)) {
+        let formattedXmlBody;
+        try {
+          formattedXmlBody = format(example.value, {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          });
+        } catch {
+          formattedXmlBody = example.value;
+        }
+        examplesBodies.push({
+          label: key,
+          body: formattedXmlBody,
+          summary: example.summary,
+        });
+      }
+    }
+    language = "xml";
+  }
+
+  if (exampleBody) {
+    return (
+      <FormItem>
+        <SchemaTabs className="openapi-tabs__schema" lazy>
+          {/* @ts-ignore */}
+          <TabItem
+            label={translate({
+              id: OPENAPI_BODY.EXAMPLE_FROM_SCHEMA,
+              message: "Example (from schema)",
+            })}
+            value="Example (from schema)"
+            default
+          >
+            <LiveApp action={dispatch} language={language} required={required}>
+              {defaultBody}
+            </LiveApp>
+          </TabItem>
+          {/* @ts-ignore */}
+          <TabItem label="Example" value="example">
+            {example.summary && <Markdown>{example.summary}</Markdown>}
+            {exampleBody && (
+              <LiveApp
+                action={dispatch}
+                language={language}
+                required={required}
+              >
+                {exampleBody}
+              </LiveApp>
+            )}
+          </TabItem>
+        </SchemaTabs>
+      </FormItem>
+    );
+  }
+
+  if (examplesBodies && examplesBodies.length > 0) {
+    return (
+      <FormItem className="openapi-explorer__form-item-body-container">
+        <SchemaTabs className="openapi-tabs__schema" lazy>
+          {/* @ts-ignore */}
+          <TabItem
+            label={translate({
+              id: OPENAPI_BODY.EXAMPLE_FROM_SCHEMA,
+              message: "Example (from schema)",
+            })}
+            value="Example (from schema)"
+            default
+          >
+            <LiveApp action={dispatch} language={language} required={required}>
+              {defaultBody}
+            </LiveApp>
+          </TabItem>
+          {examplesBodies.map((example: any) => {
+            return (
+              // @ts-ignore
+              <TabItem
+                label={example.label}
+                value={example.label}
+                key={example.label}
+              >
+                {example.summary && <Markdown>{example.summary}</Markdown>}
+                {example.body && (
+                  <LiveApp action={dispatch} language={language}>
+                    {example.body}
+                  </LiveApp>
+                )}
+              </TabItem>
+            );
+          })}
+        </SchemaTabs>
+      </FormItem>
+    );
+  }
+
+  return (
+    <FormItem>
+      <LiveApp action={dispatch} language={language} required={required}>
+        {defaultBody}
+      </LiveApp>
+    </FormItem>
+  );
+}
+
+export default BodyWrap;

package/src/theme/ApiExplorer/Body/json2xml.d.ts

@@ -0,0 +1,8 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+export default function json2xml(input: any, indent?: any): any;

package/src/theme/ApiExplorer/Body/json2xml.js

@@ -0,0 +1,43 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+export default function json2xml(o, tab) {
+  var toXml = function (v, name, ind) {
+      var xml = "";
+      if (v instanceof Array) {
+        for (var i = 0, n = v.length; i < n; i++)
+          xml += ind + toXml(v[i], name, ind + "\t") + "\n";
+      } else if (typeof v == "object") {
+        var hasChild = false;
+        xml += ind + "<" + name;
+        for (var m in v) {
+          if (m.charAt(0) === "@")
+            xml += " " + m.substr(1) + '="' + v[m].toString() + '"';
+          else hasChild = true;
+        }
+        xml += hasChild ? ">" : "/>";
+        if (hasChild) {
+          for (var m2 in v) {
+            if (m2 === "#text") xml += v[m2];
+            else if (m2 === "#cdata") xml += "<![CDATA[" + v[m2] + "]]>";
+            else if (m2.charAt(0) !== "@") xml += toXml(v[m2], m2, ind + "\t");
+          }
+          xml +=
+            (xml.charAt(xml.length - 1) === "\n" ? ind : "") +
+            "</" +
+            name +
+            ">";
+        }
+      } else {
+        xml += ind + "<" + name + ">" + v.toString() + "</" + name + ">";
+      }
+      return xml;
+    },
+    xml = "";
+  for (var m3 in o) xml += toXml(o[m3], m3, "");
+  return tab ? xml.replace(/\t/g, tab) : xml.replace(/\t|\n/g, "");
+}