docusaurus-theme-openapi-docs 0.0.0-345

package/lib-next/theme/ParamsItem/index.js

@@ -0,0 +1,68 @@
+/* ============================================================================
+ * 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 ReactMarkdown from "react-markdown";
+
+import { createDescription } from "../../markdown/createDescription";
+import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
+import { guard } from "../../markdown/utils";
+import styles from "./styles.module.css";
+
+function ParamsItem({
+  param: { description, example, examples, name, required, schema },
+}) {
+  const renderSchemaName = guard(schema, (schema) => (
+    <span className={styles.schemaName}> {getSchemaName(schema)}</span>
+  ));
+
+  const renderSchemaRequired = guard(required, () => (
+    <strong className={styles.paramsRequired}> required</strong>
+  ));
+
+  const renderSchema = guard(getQualifierMessage(schema), (message) => (
+    <div>
+      <ReactMarkdown children={createDescription(message)} />
+    </div>
+  ));
+
+  const renderDescription = guard(description, (description) => (
+    <div>
+      <ReactMarkdown children={createDescription(description)} />
+    </div>
+  ));
+
+  const renderExample = guard(example, (example) => (
+    <div>{`Example: ${example}`}</div>
+  ));
+
+  const renderExamples = guard(examples, (examples) => {
+    const exampleEntries = Object.entries(examples);
+    return (
+      <>
+        {exampleEntries.map(([k, v]) => (
+          <div>{`Example (${k}): ${v.value}`}</div>
+        ))}
+      </>
+    );
+  });
+
+  return (
+    <li className={styles.paramsItem}>
+      <strong>{name}</strong>
+      {renderSchemaName}
+      {renderSchemaRequired}
+      {renderSchema}
+      {renderDescription}
+      {renderExample}
+      {renderExamples}
+    </li>
+  );
+}
+
+export default ParamsItem;

package/lib-next/theme/ParamsItem/styles.module.css

@@ -0,0 +1,24 @@
+.paramsItem {
+  margin: 0 0 0 1rem !important;
+  position: relative;
+  padding-left: 1rem;
+  border-left: thin solid var(--ifm-color-gray-500) !important;
+  margin-top: unset !important;
+}
+
+.paramsItem:hover {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+.paramsItem:focus {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+.schemaName {
+  opacity: 0.6;
+}
+
+.paramsRequired {
+  font-size: var(--ifm-code-font-size);
+  color: var(--openapi-required);
+}

package/lib-next/theme/SchemaItem/index.js

@@ -0,0 +1,58 @@
+/* ============================================================================
+ * 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 ReactMarkdown from "react-markdown";
+
+import { createDescription } from "../../markdown/createDescription";
+import { guard } from "../../markdown/utils";
+import styles from "./styles.module.css";
+
+function SchemaItem({
+  children: collapsibleSchemaContent,
+  collapsible,
+  name,
+  qualifierMessage,
+  required,
+  schemaDescription,
+  schemaName,
+}) {
+  const renderRequired = guard(required, () => (
+    <strong className={styles.required}> required</strong>
+  ));
+
+  const renderSchemaDescription = guard(schemaDescription, (description) => (
+    <div className={styles.schemaDescription}>
+      <ReactMarkdown children={createDescription(description)} />
+    </div>
+  ));
+
+  const renderQualifierMessage = guard(qualifierMessage, (message) => (
+    <div className={styles.schemaQualifierMessage}>
+      <ReactMarkdown children={createDescription(message)} />
+    </div>
+  ));
+
+  const schemaContent = (
+    <div>
+      <strong>{name}</strong>
+      <span className={styles.schemaName}> {schemaName}</span>
+      {renderRequired}
+      {renderQualifierMessage}
+      {renderSchemaDescription}
+    </div>
+  );
+
+  return (
+    <li className={styles.schemaItem}>
+      {collapsible ? collapsibleSchemaContent : schemaContent}
+    </li>
+  );
+}
+
+export default SchemaItem;

package/lib-next/theme/SchemaItem/styles.module.css

@@ -0,0 +1,24 @@
+.schemaItem {
+  list-style: none;
+  position: relative;
+  margin: 0 !important;
+  padding: 5px 0 5px 1rem;
+  border-left: thin solid var(--ifm-color-gray-500) !important;
+}
+
+.schemaItem:hover {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+.schemaItem:focus {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+.schemaName {
+  opacity: 0.6;
+}
+
+.required {
+  font-size: var(--ifm-code-font-size);
+  color: var(--openapi-required);
+}

package/lib-next/theme-classic.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.
+ * ========================================================================== */
+
+/// <reference types="@docusaurus/theme-classic" />

package/lib-next/theme-openapi.d.ts

@@ -0,0 +1,48 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+/// <reference types="docusaurus-plugin-openapi-docs" />
+
+declare module "@docusaurus/plugin-content-docs-types" {
+  // Makes all properties visible when hovering over the type
+  type Expand<T extends Record<string, unknown>> = { [P in keyof T]: T[P] };
+
+  export type SidebarItemBase = {
+    className?: string;
+    customProps?: Record<string, unknown>;
+  };
+
+  export type SidebarItemLink = SidebarItemBase & {
+    type: "link";
+    href: string;
+    label: string;
+    docId: string;
+  };
+
+  type SidebarItemCategoryBase = SidebarItemBase & {
+    type: "category";
+    label: string;
+    collapsed: boolean;
+    collapsible: boolean;
+  };
+
+  export type PropSidebarItemCategory = Expand<
+    SidebarItemCategoryBase & {
+      items: PropSidebarItem[];
+    }
+  >;
+
+  export type PropSidebarItem = SidebarItemLink | PropSidebarItemCategory;
+  export type PropSidebar = PropSidebarItem[];
+  export type PropSidebars = {
+    [sidebarId: string]: PropSidebar;
+  };
+}
+
+declare module "docusaurus-theme-openapi-docs" {
+  export type ThemeConfig = Partial<import("./types").ThemeConfig>;
+}

package/lib-next/theme-translations.d.ts

@@ -0,0 +1,9 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+// TODO: Remove this when https://github.com/facebook/docusaurus/issues/6087 is resolved.
+declare module "@docusaurus/theme-translations";

package/lib-next/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "docusaurus-theme-openapi-docs",
+  "description": "OpenAPI theme for Docusaurus.",
+  "version": "0.0.0-345",
+  "license": "MIT",
+  "keywords": [
+    "openapi",
+    "documentation",
+    "docusaurus",
+    "websites",
+    "theme"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs.git",
+    "directory": "packages/docusaurus-theme-openapi-docs"
+  },
+  "bugs": {
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues"
+  },
+  "types": "src/theme-openapi.d.ts",
+  "main": "lib/index.js",
+  "scripts": {
+    "build": "tsc --noEmit && yarn babel:lib && yarn babel:lib-next && yarn format:lib-next",
+    "watch": "concurrently --names \"lib,lib-next,tsc\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\" \"yarn tsc --watch\"",
+    "babel:lib": "cross-env BABEL_ENV=lib babel src -d lib --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
+    "babel:lib-next": "cross-env BABEL_ENV=lib-next babel src -d lib-next --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
+    "format:lib-next": "prettier --config ../../.prettierrc.json --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.0-beta.18",
+    "@docusaurus/types": "2.0.0-beta.18",
+    "@types/concurrently": "^6.3.0",
+    "@types/crypto-js": "^4.1.0",
+    "@types/fs-extra": "^9.0.13",
+    "@types/lodash": "^4.14.176",
+    "@types/mdx-js__react": "^1.5.4",
+    "@types/rtlcss": "^3.1.1",
+    "concurrently": "^5.2.0"
+  },
+  "dependencies": {
+    "@docusaurus/theme-common": "2.0.0-beta.18",
+    "@mdx-js/react": "^1.6.21",
+    "@monaco-editor/react": "^4.3.1",
+    "@paloaltonetworks/postman-code-generators": "1.1.5-hotfix.5",
+    "@paloaltonetworks/postman-collection": "^4.1.0",
+    "@reduxjs/toolkit": "^1.7.1",
+    "buffer": "^6.0.3",
+    "clsx": "^1.1.1",
+    "crypto-js": "^4.1.1",
+    "docusaurus-plugin-openapi-docs": "0.0.0-345",
+    "immer": "^9.0.7",
+    "lodash": "^4.17.20",
+    "monaco-editor": "^0.31.1",
+    "prism-react-renderer": "^1.2.1",
+    "process": "^0.11.10",
+    "react-magic-dropzone": "^1.0.1",
+    "react-markdown": "^8.0.1",
+    "react-redux": "^7.2.0",
+    "redux-devtools-extension": "^2.13.8",
+    "webpack": "^5.61.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8.4 || ^17.0.0",
+    "react-dom": "^16.8.4 || ^17.0.0"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "gitHead": "3c372c894fcdf0e84cbbc0e8e5e4e8e3d770fbb4"
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/* ============================================================================
+ * 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 path from "path";
+
+import type { Plugin } from "@docusaurus/types";
+import { ProvidePlugin } from "webpack";
+
+export default function docusaurusThemeOpenAPI(): Plugin<void> {
+  return {
+    name: "docusaurus-theme-openapi",
+
+    getThemePath() {
+      return path.join(__dirname, "..", "lib-next", "theme");
+    },
+
+    getTypeScriptThemePath() {
+      return path.resolve(__dirname, "..", "src", "theme");
+    },
+
+    configureWebpack() {
+      return {
+        plugins: [
+          new ProvidePlugin({
+            Buffer: [require.resolve("buffer/"), "Buffer"],
+            process: require.resolve("process/browser"),
+          }),
+        ],
+        resolve: {
+          fallback: {
+            buffer: require.resolve("buffer/"),
+            process: require.resolve("process/browser"),
+          },
+        },
+      };
+    },
+  };
+}

package/src/markdown/createDescription.ts

@@ -0,0 +1,13 @@
+/* ============================================================================
+ * 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 function createDescription(description: string | undefined) {
+  if (!description) {
+    return "";
+  }
+  return `\n\n${description}\n\n`;
+}

package/src/markdown/schema.ts

@@ -0,0 +1,115 @@
+/* ============================================================================
+ * 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 { SchemaObject } from "../types";
+
+function prettyName(schema: SchemaObject, circular?: boolean) {
+  if (schema.$ref) {
+    return schema.$ref.replace("#/components/schemas/", "") + circular
+      ? " (circular)"
+      : "";
+  }
+
+  if (schema.format) {
+    return schema.format;
+  }
+
+  if (schema.allOf) {
+    return "object";
+  }
+
+  if (schema.type === "object") {
+    return schema.xml?.name ?? schema.type;
+  }
+
+  return schema.title ?? schema.type;
+}
+
+export function getSchemaName(
+  schema: SchemaObject,
+  circular?: boolean
+): string {
+  if (schema.items) {
+    return prettyName(schema.items, circular) + "[]";
+  }
+
+  return prettyName(schema, circular) ?? "";
+}
+
+export function getQualifierMessage(schema?: SchemaObject): string | undefined {
+  // TODO:
+  // - maxItems
+  // - minItems
+  // - uniqueItems
+  // - maxProperties
+  // - minProperties
+  // - multipleOf
+  if (!schema) {
+    return undefined;
+  }
+
+  if (schema.items) {
+    return getQualifierMessage(schema.items);
+  }
+
+  let message = "**Possible values:** ";
+
+  let qualifierGroups = [];
+
+  if (schema.minLength || schema.maxLength) {
+    let lengthQualifier = "";
+    if (schema.minLength) {
+      lengthQualifier += `${schema.minLength} ≤ `;
+    }
+    lengthQualifier += "length";
+    if (schema.maxLength) {
+      lengthQualifier += ` ≤ ${schema.maxLength}`;
+    }
+    qualifierGroups.push(lengthQualifier);
+  }
+
+  if (
+    schema.minimum ||
+    schema.maximum ||
+    typeof schema.exclusiveMinimum === "number" ||
+    typeof schema.exclusiveMaximum === "number"
+  ) {
+    let minmaxQualifier = "";
+    if (typeof schema.exclusiveMinimum === "number") {
+      minmaxQualifier += `${schema.exclusiveMinimum} < `;
+    } else if (schema.minimum && !schema.exclusiveMinimum) {
+      minmaxQualifier += `${schema.minimum} ≤ `;
+    } else if (schema.minimum && schema.exclusiveMinimum === true) {
+      minmaxQualifier += `${schema.minimum} < `;
+    }
+    minmaxQualifier += "value";
+    if (typeof schema.exclusiveMaximum === "number") {
+      minmaxQualifier += ` < ${schema.exclusiveMaximum}`;
+    } else if (schema.maximum && !schema.exclusiveMaximum) {
+      minmaxQualifier += ` ≤ ${schema.maximum}`;
+    } else if (schema.maximum && schema.exclusiveMaximum === true) {
+      minmaxQualifier += ` < ${schema.maximum}`;
+    }
+    qualifierGroups.push(minmaxQualifier);
+  }
+
+  if (schema.pattern) {
+    qualifierGroups.push(
+      `Value must match regular expression \`${schema.pattern}\``
+    );
+  }
+
+  if (schema.enum) {
+    qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
+  }
+
+  if (qualifierGroups.length === 0) {
+    return undefined;
+  }
+
+  return message + qualifierGroups.join(", ");
+}

package/src/markdown/utils.ts

@@ -0,0 +1,39 @@
+/* ============================================================================
+ * 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 type Children = string | undefined | (string | undefined)[];
+
+export type Props = Record<string, any> & { children?: Children };
+
+export function create(tag: string, props: Props): string {
+  const { children, ...rest } = props;
+
+  let propString = "";
+  for (const [key, value] of Object.entries(rest)) {
+    propString += ` ${key}={${JSON.stringify(value)}}`;
+  }
+
+  return `<${tag}${propString}>${render(children)}</${tag}>`;
+}
+
+export function guard<T>(
+  value: T | undefined,
+  cb: (value: T) => Children
+): string {
+  if (value) {
+    const children = cb(value);
+    return render(children);
+  }
+  return "";
+}
+
+export function render(children: Children): string {
+  if (Array.isArray(children)) {
+    return children.filter((c) => c !== undefined).join("");
+  }
+  return children ?? "";
+}

package/src/postman-code-generators.d.ts

@@ -0,0 +1,9 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+// TODO: Remove this when https://github.com/facebook/docusaurus/issues/6087 is resolved.
+declare module "@paloaltonetworks/postman-code-generators";

package/src/react-magic-dropzone.d.ts

@@ -0,0 +1,9 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+// TODO: Remove this when https://github.com/facebook/docusaurus/issues/6087 is resolved.
+declare module "react-magic-dropzone";

package/src/theme/ApiDemoPanel/Accept/index.tsx

@@ -0,0 +1,35 @@
+/* ============================================================================
+ * 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 { useTypedDispatch, useTypedSelector } from "../hooks";
+import FormItem from "./../FormItem";
+import FormSelect from "./../FormSelect";
+import { setAccept } from "./slice";
+
+function Accept() {
+  const value = useTypedSelector((state) => state.accept.value);
+  const options = useTypedSelector((state) => state.accept.options);
+  const dispatch = useTypedDispatch();
+
+  if (options.length <= 1) {
+    return null;
+  }
+
+  return (
+    <FormItem label="Accept">
+      <FormSelect
+        value={value}
+        options={options}
+        onChange={(e) => dispatch(setAccept(e.target.value))}
+      />
+    </FormItem>
+  );
+}
+
+export default Accept;

package/src/theme/ApiDemoPanel/Accept/slice.ts

@@ -0,0 +1,29 @@
+/* ============================================================================
+ * 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";
+
+export interface State {
+  value: string;
+  options: string[];
+}
+
+const initialState: State = {} as any;
+
+export const slice = createSlice({
+  name: "accept",
+  initialState,
+  reducers: {
+    setAccept: (state, action: PayloadAction<string>) => {
+      state.value = action.payload;
+    },
+  },
+});
+
+export const { setAccept } = slice.actions;
+
+export default slice.reducer;

package/src/theme/ApiDemoPanel/Authorization/auth-types.ts

@@ -0,0 +1,26 @@
+/* ============================================================================
+ * 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 function getAuthDataKeys(security: { [key: string]: any }) {
+  // Bearer Auth
+  if (security.type === "http" && security.scheme === "bearer") {
+    return ["token"];
+  }
+
+  // Basic Auth
+  if (security.type === "http" && security.scheme === "basic") {
+    return ["username", "password"];
+  }
+
+  // API Auth
+  if (security.type === "apiKey") {
+    return ["apiKey"];
+  }
+
+  // none
+  return [];
+}