docusaurus-theme-openapi-docs 0.0.0-1000

package/lib/theme/ApiExplorer/Authorization/index.js

@@ -0,0 +1,160 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importDefault(require("react"));
+const FormItem_1 = __importDefault(require("@theme/ApiExplorer/FormItem"));
+const FormSelect_1 = __importDefault(require("@theme/ApiExplorer/FormSelect"));
+const FormTextInput_1 = __importDefault(
+  require("@theme/ApiExplorer/FormTextInput")
+);
+const hooks_1 = require("@theme/ApiItem/hooks");
+const slice_1 = require("./slice");
+function Authorization() {
+  const data = (0, hooks_1.useTypedSelector)((state) => state.auth.data);
+  const options = (0, hooks_1.useTypedSelector)((state) => state.auth.options);
+  const selected = (0, hooks_1.useTypedSelector)(
+    (state) => state.auth.selected
+  );
+  const dispatch = (0, hooks_1.useTypedDispatch)();
+  if (selected === undefined) {
+    return null;
+  }
+  const selectedAuth = options[selected];
+  const optionKeys = Object.keys(options);
+  return react_1.default.createElement(
+    "div",
+    null,
+    optionKeys.length > 1 &&
+      react_1.default.createElement(
+        FormItem_1.default,
+        { label: "Security Scheme" },
+        react_1.default.createElement(FormSelect_1.default, {
+          options: optionKeys,
+          value: selected,
+          onChange: (e) => {
+            dispatch((0, slice_1.setSelectedAuth)(e.target.value));
+          },
+        })
+      ),
+    selectedAuth.map((a) => {
+      if (a.type === "http" && a.scheme === "bearer") {
+        return react_1.default.createElement(
+          FormItem_1.default,
+          { label: "Bearer Token", key: a.key + "-bearer" },
+          react_1.default.createElement(FormTextInput_1.default, {
+            placeholder: "Bearer Token",
+            password: true,
+            value: data[a.key].token ?? "",
+            onChange: (e) => {
+              const value = e.target.value;
+              dispatch(
+                (0, slice_1.setAuthData)({
+                  scheme: a.key,
+                  key: "token",
+                  value: value ? value : undefined,
+                })
+              );
+            },
+          })
+        );
+      }
+      if (a.type === "oauth2") {
+        return react_1.default.createElement(
+          FormItem_1.default,
+          { label: "Bearer Token", key: a.key + "-oauth2" },
+          react_1.default.createElement(FormTextInput_1.default, {
+            placeholder: "Bearer Token",
+            password: true,
+            value: data[a.key].token ?? "",
+            onChange: (e) => {
+              const value = e.target.value;
+              dispatch(
+                (0, slice_1.setAuthData)({
+                  scheme: a.key,
+                  key: "token",
+                  value: value ? value : undefined,
+                })
+              );
+            },
+          })
+        );
+      }
+      if (a.type === "http" && a.scheme === "basic") {
+        return react_1.default.createElement(
+          react_1.default.Fragment,
+          { key: a.key + "-basic" },
+          react_1.default.createElement(
+            FormItem_1.default,
+            { label: "Username" },
+            react_1.default.createElement(FormTextInput_1.default, {
+              placeholder: "Username",
+              value: data[a.key].username ?? "",
+              onChange: (e) => {
+                const value = e.target.value;
+                dispatch(
+                  (0, slice_1.setAuthData)({
+                    scheme: a.key,
+                    key: "username",
+                    value: value ? value : undefined,
+                  })
+                );
+              },
+            })
+          ),
+          react_1.default.createElement(
+            FormItem_1.default,
+            { label: "Password" },
+            react_1.default.createElement(FormTextInput_1.default, {
+              placeholder: "Password",
+              password: true,
+              value: data[a.key].password ?? "",
+              onChange: (e) => {
+                const value = e.target.value;
+                dispatch(
+                  (0, slice_1.setAuthData)({
+                    scheme: a.key,
+                    key: "password",
+                    value: value ? value : undefined,
+                  })
+                );
+              },
+            })
+          )
+        );
+      }
+      if (a.type === "apiKey") {
+        return react_1.default.createElement(
+          FormItem_1.default,
+          { label: `${a.key}`, key: a.key + "-apikey" },
+          react_1.default.createElement(FormTextInput_1.default, {
+            placeholder: `${a.key}`,
+            password: true,
+            value: data[a.key].apiKey ?? "",
+            onChange: (e) => {
+              const value = e.target.value;
+              dispatch(
+                (0, slice_1.setAuthData)({
+                  scheme: a.key,
+                  key: "apiKey",
+                  value: value ? value : undefined,
+                })
+              );
+            },
+          })
+        );
+      }
+      return null;
+    })
+  );
+}
+exports.default = Authorization;

package/lib/theme/ApiExplorer/Authorization/slice.d.ts

@@ -0,0 +1,40 @@
+import { PayloadAction } from "@reduxjs/toolkit";
+import { SecurityRequirementObject, SecuritySchemeObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
+export declare function createAuth({ security, securitySchemes, options: opts, }: {
+    security?: SecurityRequirementObject[];
+    securitySchemes?: {
+        [key: string]: SecuritySchemeObject;
+    };
+    options?: ThemeConfig["api"];
+}): AuthState;
+export type Scheme = {
+    key: string;
+    scopes: string[];
+} & SecuritySchemeObject;
+export interface AuthState {
+    data: {
+        [scheme: string]: {
+            [key: string]: string | undefined;
+        };
+    };
+    options: {
+        [key: string]: Scheme[];
+    };
+    selected?: string;
+}
+export declare const slice: import("@reduxjs/toolkit").Slice<AuthState, {
+    setAuthData: (state: import("immer/dist/internal").WritableDraft<AuthState>, action: PayloadAction<{
+        scheme: string;
+        key: string;
+        value?: string;
+    }>) => void;
+    setSelectedAuth: (state: import("immer/dist/internal").WritableDraft<AuthState>, action: PayloadAction<string>) => void;
+}, "auth">;
+export declare const setAuthData: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    scheme: string;
+    key: string;
+    value?: string;
+}, "auth/setAuthData">, setSelectedAuth: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "auth/setSelectedAuth">;
+declare const _default: import("redux").Reducer<AuthState>;
+export default _default;

package/lib/theme/ApiExplorer/Authorization/slice.js

@@ -0,0 +1,102 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSelectedAuth = exports.setAuthData = exports.slice = void 0;
+exports.createAuth = createAuth;
+const toolkit_1 = require("@reduxjs/toolkit");
+const storage_utils_1 = require("@theme/ApiExplorer/storage-utils");
+const auth_types_1 = require("./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 }
+function createAuth({ security, securitySchemes, options: opts }) {
+  const storage = (0, storage_utils_1.createStorage)("sessionStorage");
+  let data = {};
+  let 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 = (0, auth_types_1.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((0, storage_utils_1.hashArray)(Object.keys(options))) ??
+      undefined;
+  } catch {}
+  return {
+    data,
+    options,
+    selected: persisted ?? Object.keys(options)[0],
+  };
+}
+const initialState = {};
+exports.slice = (0, toolkit_1.createSlice)({
+  name: "auth",
+  initialState,
+  reducers: {
+    setAuthData: (state, action) => {
+      const { scheme, key, value } = action.payload;
+      state.data[scheme][key] = value;
+    },
+    setSelectedAuth: (state, action) => {
+      state.selected = action.payload;
+    },
+  },
+});
+(_a = exports.slice.actions),
+  (exports.setAuthData = _a.setAuthData),
+  (exports.setSelectedAuth = _a.setSelectedAuth);
+exports.default = exports.slice.reducer;

package/lib/theme/ApiExplorer/Body/index.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+import { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+export interface Props {
+    jsonRequestBodyExample: string;
+    requestBodyMetadata?: RequestBodyObject;
+    methods?: any;
+    required?: boolean;
+}
+declare function BodyWrap({ requestBodyMetadata, jsonRequestBodyExample, methods, required, }: Props): React.JSX.Element | null;
+export default BodyWrap;

package/lib/theme/ApiExplorer/Body/index.js

@@ -0,0 +1,381 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importDefault(require("react"));
+const json2xml_1 = __importDefault(require("@theme/ApiExplorer/Body/json2xml"));
+const FormFileUpload_1 = __importDefault(
+  require("@theme/ApiExplorer/FormFileUpload")
+);
+const FormItem_1 = __importDefault(require("@theme/ApiExplorer/FormItem"));
+const FormSelect_1 = __importDefault(require("@theme/ApiExplorer/FormSelect"));
+const FormTextInput_1 = __importDefault(
+  require("@theme/ApiExplorer/FormTextInput")
+);
+const LiveEditor_1 = __importDefault(require("@theme/ApiExplorer/LiveEditor"));
+const hooks_1 = require("@theme/ApiItem/hooks");
+const Markdown_1 = __importDefault(require("@theme/Markdown"));
+const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
+const TabItem_1 = __importDefault(require("@theme/TabItem"));
+const xml_formatter_1 = __importDefault(require("xml-formatter"));
+const slice_1 = require("./slice");
+function BodyWrap({
+  requestBodyMetadata,
+  jsonRequestBodyExample,
+  methods,
+  required,
+}) {
+  const contentType = (0, hooks_1.useTypedSelector)(
+    (state) => 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 react_1.default.createElement(Body, {
+    requestBodyMetadata: requestBodyMetadata,
+    jsonRequestBodyExample: jsonRequestBodyExample,
+    required: required,
+  });
+}
+function Body({
+  requestBodyMetadata,
+  jsonRequestBodyExample,
+  methods,
+  required,
+}) {
+  const contentType = (0, hooks_1.useTypedSelector)(
+    (state) => state.contentType.value
+  );
+  const dispatch = (0, hooks_1.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 react_1.default.createElement(
+      FormItem_1.default,
+      null,
+      react_1.default.createElement(FormFileUpload_1.default, {
+        placeholder: schema.description || "Body",
+        onChange: (file) => {
+          if (file === undefined) {
+            dispatch((0, slice_1.clearRawBody)());
+            return;
+          }
+          dispatch(
+            (0, slice_1.setFileRawBody)({
+              src: `/path/to/${file.name}`,
+              content: file,
+            })
+          );
+        },
+      })
+    );
+  }
+  if (
+    (contentType === "multipart/form-data" ||
+      contentType === "application/x-www-form-urlencoded") &&
+    schema?.type === "object"
+  ) {
+    return react_1.default.createElement(
+      FormItem_1.default,
+      { className: "openapi-explorer__form-item-body-container" },
+      react_1.default.createElement(
+        "div",
+        null,
+        Object.entries(schema.properties ?? {}).map(([key, val]) => {
+          if (val.format === "binary") {
+            return react_1.default.createElement(
+              FormItem_1.default,
+              {
+                key: key,
+                label: key,
+                required:
+                  Array.isArray(schema.required) &&
+                  schema.required.includes(key),
+              },
+              react_1.default.createElement(FormFileUpload_1.default, {
+                placeholder: val.description || key,
+                onChange: (file) => {
+                  if (file === undefined) {
+                    dispatch((0, slice_1.clearFormBodyKey)(key));
+                    return;
+                  }
+                  dispatch(
+                    (0, slice_1.setFileFormBody)({
+                      key: key,
+                      value: {
+                        src: `/path/to/${file.name}`,
+                        content: file,
+                      },
+                    })
+                  );
+                },
+              })
+            );
+          }
+          if (val.enum) {
+            return react_1.default.createElement(
+              FormItem_1.default,
+              {
+                key: key,
+                label: key,
+                required:
+                  Array.isArray(schema.required) &&
+                  schema.required.includes(key),
+              },
+              react_1.default.createElement(FormSelect_1.default, {
+                options: ["---", ...val.enum],
+                onChange: (e) => {
+                  const val = e.target.value;
+                  if (val === "---") {
+                    dispatch((0, slice_1.clearFormBodyKey)(key));
+                  } else {
+                    dispatch(
+                      (0, slice_1.setStringFormBody)({
+                        key: key,
+                        value: val,
+                      })
+                    );
+                  }
+                },
+              })
+            );
+          }
+          // TODO: support all the other types.
+          return react_1.default.createElement(
+            FormItem_1.default,
+            {
+              key: key,
+              label: key,
+              required:
+                Array.isArray(schema.required) && schema.required.includes(key),
+            },
+            react_1.default.createElement(FormTextInput_1.default, {
+              paramName: key,
+              isRequired:
+                Array.isArray(schema.required) && schema.required.includes(key),
+              placeholder: val.description || key,
+              onChange: (e) => {
+                dispatch(
+                  (0, slice_1.setStringFormBody)({
+                    key: key,
+                    value: e.target.value,
+                  })
+                );
+              },
+            })
+          );
+        })
+      )
+    );
+  }
+  let language = "plaintext";
+  let defaultBody = ""; //"body content";
+  let exampleBody;
+  let examplesBodies = [];
+  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 = (0, xml_formatter_1.default)(
+          (0, json2xml_1.default)(jsonRequestBodyExample, ""),
+          {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          }
+        );
+      } catch {
+        defaultBody = (0, json2xml_1.default)(jsonRequestBodyExample);
+      }
+    }
+    if (example) {
+      try {
+        exampleBody = (0, xml_formatter_1.default)(
+          (0, json2xml_1.default)(example, ""),
+          {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          }
+        );
+      } catch {
+        exampleBody = (0, json2xml_1.default)(example);
+      }
+    }
+    if (examples) {
+      for (const [key, example] of Object.entries(examples)) {
+        let formattedXmlBody;
+        try {
+          formattedXmlBody = (0, xml_formatter_1.default)(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 react_1.default.createElement(
+      FormItem_1.default,
+      null,
+      react_1.default.createElement(
+        SchemaTabs_1.default,
+        { className: "openapi-tabs__schema", lazy: true },
+        react_1.default.createElement(
+          TabItem_1.default,
+          {
+            label: "Example (from schema)",
+            value: "Example (from schema)",
+            default: true,
+          },
+          react_1.default.createElement(
+            LiveEditor_1.default,
+            { action: dispatch, language: language, required: required },
+            defaultBody
+          )
+        ),
+        react_1.default.createElement(
+          TabItem_1.default,
+          { label: "Example", value: "example" },
+          example.summary &&
+            react_1.default.createElement(
+              Markdown_1.default,
+              null,
+              example.summary
+            ),
+          exampleBody &&
+            react_1.default.createElement(
+              LiveEditor_1.default,
+              { action: dispatch, language: language, required: required },
+              exampleBody
+            )
+        )
+      )
+    );
+  }
+  if (examplesBodies && examplesBodies.length > 0) {
+    return react_1.default.createElement(
+      FormItem_1.default,
+      { className: "openapi-explorer__form-item-body-container" },
+      react_1.default.createElement(
+        SchemaTabs_1.default,
+        { className: "openapi-tabs__schema", lazy: true },
+        react_1.default.createElement(
+          TabItem_1.default,
+          {
+            label: "Example (from schema)",
+            value: "Example (from schema)",
+            default: true,
+          },
+          react_1.default.createElement(
+            LiveEditor_1.default,
+            { action: dispatch, language: language, required: required },
+            defaultBody
+          )
+        ),
+        examplesBodies.map((example) => {
+          return (
+            // @ts-ignore
+            react_1.default.createElement(
+              TabItem_1.default,
+              {
+                label: example.label,
+                value: example.label,
+                key: example.label,
+              },
+              example.summary &&
+                react_1.default.createElement(
+                  Markdown_1.default,
+                  null,
+                  example.summary
+                ),
+              example.body &&
+                react_1.default.createElement(
+                  LiveEditor_1.default,
+                  { action: dispatch, language: language },
+                  example.body
+                )
+            )
+          );
+        })
+      )
+    );
+  }
+  return react_1.default.createElement(
+    FormItem_1.default,
+    null,
+    react_1.default.createElement(
+      LiveEditor_1.default,
+      { action: dispatch, language: language, required: required },
+      defaultBody
+    )
+  );
+}
+exports.default = BodyWrap;