docusaurus-theme-openapi-docs 0.0.0-1000

package/src/theme/ApiItem/Layout/index.tsx

@@ -0,0 +1,85 @@
+/* ============================================================================
+ * 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, { type JSX } from "react";
+
+import { useDoc } from "@docusaurus/plugin-content-docs/client";
+import { useWindowSize } from "@docusaurus/theme-common";
+import type { Props } from "@theme/ApiItem/Layout";
+import ContentVisibility from "@theme/ContentVisibility";
+import DocBreadcrumbs from "@theme/DocBreadcrumbs";
+import DocItemContent from "@theme/DocItem/Content";
+import DocItemFooter from "@theme/DocItem/Footer";
+import DocItemPaginator from "@theme/DocItem/Paginator";
+import DocItemTOCDesktop from "@theme/DocItem/TOC/Desktop";
+import DocItemTOCMobile from "@theme/DocItem/TOC/Mobile";
+import DocVersionBadge from "@theme/DocVersionBadge";
+import DocVersionBanner from "@theme/DocVersionBanner";
+import clsx from "clsx";
+
+import styles from "./styles.module.css";
+
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const { frontMatter, toc } = useDoc();
+  const windowSize = useWindowSize();
+
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+
+  const desktop =
+    canRender && (windowSize === "desktop" || windowSize === "ssr") ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+
+export default function DocItemLayout({ children }: Props): JSX.Element {
+  const docTOC = useDocTOC();
+  const { metadata } = useDoc();
+  const { frontMatter } = useDoc();
+  const api = frontMatter.api;
+  const schema = frontMatter.schema;
+  return (
+    <div className="row">
+      <div className={clsx("col", !docTOC.hidden && styles.docItemCol)}>
+        <ContentVisibility metadata={metadata} />
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <div className="row">
+              <div
+                className={clsx("col", api || schema ? "col--7" : "col--12")}
+              >
+                <DocItemFooter />
+              </div>
+            </div>
+          </article>
+          <div className="row">
+            <div className={clsx("col", api || schema ? "col--7" : "col--12")}>
+              <DocItemPaginator />
+            </div>
+          </div>
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}

package/src/theme/ApiItem/Layout/styles.module.css

@@ -0,0 +1,17 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}

package/src/theme/ApiItem/hooks.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.
+ * ========================================================================== */
+
+import { TypedUseSelectorHook, useDispatch, useSelector } from "react-redux";
+
+import type { RootState, AppDispatch } from "./store";
+
+export const useTypedDispatch = () => useDispatch<AppDispatch>();
+export const useTypedSelector: TypedUseSelectorHook<RootState> = useSelector;

package/src/theme/ApiItem/index.tsx

@@ -0,0 +1,222 @@
+/* ============================================================================
+ * 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 BrowserOnly from "@docusaurus/BrowserOnly";
+import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
+import { DocProvider } from "@docusaurus/plugin-content-docs/client";
+import { HtmlClassNameProvider } from "@docusaurus/theme-common";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import { createAuth } from "@theme/ApiExplorer/Authorization/slice";
+import { createPersistanceMiddleware } from "@theme/ApiExplorer/persistanceMiddleware";
+import DocItemLayout from "@theme/ApiItem/Layout";
+import CodeBlock from "@theme/CodeBlock";
+import type { Props } from "@theme/DocItem";
+import DocItemMetadata from "@theme/DocItem/Metadata";
+import SkeletonLoader from "@theme/SkeletonLoader";
+import clsx from "clsx";
+import {
+  ParameterObject,
+  ServerObject,
+} from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { ApiItem as ApiItemType } from "docusaurus-plugin-openapi-docs/src/types";
+import type {
+  DocFrontMatter,
+  ThemeConfig,
+} from "docusaurus-theme-openapi-docs/src/types";
+import { ungzip } from "pako";
+import { Provider } from "react-redux";
+
+import { createStoreWithoutState, createStoreWithState } from "./store";
+
+let ApiExplorer = (_: { item: any; infoPath: any }) => <div />;
+
+if (ExecutionEnvironment.canUseDOM) {
+  ApiExplorer = require("@theme/ApiExplorer").default;
+}
+
+interface ApiFrontMatter extends DocFrontMatter {
+  readonly api?: ApiItemType;
+}
+
+interface SchemaFrontMatter extends DocFrontMatter {
+  readonly schema?: boolean;
+}
+
+interface SampleFrontMatter extends DocFrontMatter {
+  readonly sample?: any;
+}
+
+function base64ToUint8Array(base64: string) {
+  const binary = atob(base64);
+  const len = binary.length;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// @ts-ignore
+export default function ApiItem(props: Props): JSX.Element {
+  const docHtmlClassName = `docs-doc-id-${props.content.metadata.id}`;
+  const MDXComponent = props.content;
+  const { frontMatter } = MDXComponent;
+  const { info_path: infoPath } = frontMatter as DocFrontMatter;
+  let { api } = frontMatter as ApiFrontMatter;
+  const { schema } = frontMatter as SchemaFrontMatter;
+  const { sample } = frontMatter as SampleFrontMatter;
+  // decompress and parse
+  if (api) {
+    try {
+      api = JSON.parse(
+        new TextDecoder().decode(ungzip(base64ToUint8Array(api as any)))
+      );
+    } catch {}
+  }
+  const { siteConfig } = useDocusaurusContext();
+  const themeConfig = siteConfig.themeConfig as ThemeConfig;
+  const options = themeConfig.api;
+  const isBrowser = useIsBrowser();
+
+  // Regex for 2XX status
+  const statusRegex = new RegExp("(20[0-9]|2[1-9][0-9])");
+
+  // Define store2
+  let store2: any = {};
+  const persistanceMiddleware = createPersistanceMiddleware(options);
+
+  // Init store for SSR
+  if (!isBrowser) {
+    store2 = createStoreWithoutState({}, [persistanceMiddleware]);
+  }
+
+  // Init store for CSR to hydrate components
+  if (isBrowser) {
+    // Create list of only 2XX response content types to create request samples from
+    let acceptArray: any = [];
+    for (const [code, content] of Object.entries(api?.responses ?? [])) {
+      if (statusRegex.test(code)) {
+        acceptArray.push(Object.keys(content.content ?? {}));
+      }
+    }
+    acceptArray = acceptArray.flat();
+
+    const content = api?.requestBody?.content ?? {};
+    const contentTypeArray = Object.keys(content);
+    const servers = api?.servers ?? [];
+    const params = {
+      path: [] as ParameterObject[],
+      query: [] as ParameterObject[],
+      header: [] as ParameterObject[],
+      cookie: [] as ParameterObject[],
+    };
+    api?.parameters?.forEach(
+      (param: { in: "path" | "query" | "header" | "cookie" }) => {
+        const paramType = param.in;
+        const paramsArray: ParameterObject[] = params[paramType];
+        paramsArray.push(param as ParameterObject);
+      }
+    );
+    const auth = createAuth({
+      security: api?.security,
+      securitySchemes: api?.securitySchemes,
+      options,
+    });
+    // TODO: determine way to rehydrate without flashing
+    // const acceptValue = window?.sessionStorage.getItem("accept");
+    // const contentTypeValue = window?.sessionStorage.getItem("contentType");
+    const server = window?.sessionStorage.getItem("server");
+    const serverObject = (JSON.parse(server!) as ServerObject) ?? {};
+
+    store2 = createStoreWithState(
+      {
+        accept: {
+          value: acceptArray[0],
+          options: acceptArray,
+        },
+        contentType: {
+          value: contentTypeArray[0],
+          options: contentTypeArray,
+        },
+        server: {
+          value: serverObject.url ? serverObject : undefined,
+          options: servers,
+        },
+        response: { value: undefined },
+        body: { type: "empty" },
+        params,
+        auth,
+      },
+      [persistanceMiddleware]
+    );
+  }
+
+  if (api) {
+    return (
+      <DocProvider content={props.content}>
+        <HtmlClassNameProvider className={docHtmlClassName}>
+          <DocItemMetadata />
+          <DocItemLayout>
+            <Provider store={store2}>
+              <div className={clsx("row", "theme-api-markdown")}>
+                <div className="col col--7 openapi-left-panel__container">
+                  <MDXComponent />
+                </div>
+                <div className="col col--5 openapi-right-panel__container">
+                  <BrowserOnly fallback={<SkeletonLoader size="lg" />}>
+                    {() => {
+                      return <ApiExplorer item={api} infoPath={infoPath} />;
+                    }}
+                  </BrowserOnly>
+                </div>
+              </div>
+            </Provider>
+          </DocItemLayout>
+        </HtmlClassNameProvider>
+      </DocProvider>
+    );
+  } else if (schema) {
+    return (
+      <DocProvider content={props.content}>
+        <HtmlClassNameProvider className={docHtmlClassName}>
+          <DocItemMetadata />
+          <DocItemLayout>
+            <div className={clsx("row", "theme-api-markdown")}>
+              <div className="col col--7 openapi-left-panel__container schema">
+                <MDXComponent />
+              </div>
+              <div className="col col--5 openapi-right-panel__container">
+                <CodeBlock language="json" title={`${frontMatter.title}`}>
+                  {JSON.stringify(sample, null, 2)}
+                </CodeBlock>
+              </div>
+            </div>
+          </DocItemLayout>
+        </HtmlClassNameProvider>
+      </DocProvider>
+    );
+  }
+
+  // Non-API docs
+  return (
+    <DocProvider content={props.content}>
+      <HtmlClassNameProvider className={docHtmlClassName}>
+        <DocItemMetadata />
+        <DocItemLayout>
+          <div className="row">
+            <div className="col col--12 markdown">
+              <MDXComponent />
+            </div>
+          </div>
+        </DocItemLayout>
+      </HtmlClassNameProvider>
+    </DocProvider>
+  );
+}

package/src/theme/ApiItem/store.ts

@@ -0,0 +1,51 @@
+/* ============================================================================
+ * 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 { configureStore, combineReducers } from "@reduxjs/toolkit";
+import accept from "@theme/ApiExplorer/Accept/slice";
+import auth from "@theme/ApiExplorer/Authorization/slice";
+import body from "@theme/ApiExplorer/Body/slice";
+import contentType from "@theme/ApiExplorer/ContentType/slice";
+import params from "@theme/ApiExplorer/ParamOptions/slice";
+import response from "@theme/ApiExplorer/Response/slice";
+import server from "@theme/ApiExplorer/Server/slice";
+
+const rootReducer = combineReducers({
+  accept,
+  contentType,
+  response,
+  server,
+  body,
+  params,
+  auth,
+});
+
+export type RootState = ReturnType<typeof rootReducer>;
+
+export const createStoreWithState = (
+  preloadedState: RootState,
+  middlewares: any[]
+) =>
+  configureStore({
+    reducer: rootReducer,
+    preloadedState,
+    middleware: (getDefaultMiddleware) =>
+      getDefaultMiddleware().concat(...middlewares),
+  });
+
+export const createStoreWithoutState = (
+  preloadedState: {},
+  middlewares: any[]
+) =>
+  configureStore({
+    reducer: rootReducer,
+    preloadedState,
+    middleware: (getDefaultMiddleware) =>
+      getDefaultMiddleware().concat(...middlewares),
+  });
+
+export type AppDispatch = ReturnType<typeof createStoreWithState>["dispatch"];

package/src/theme/ApiLogo/index.tsx

@@ -0,0 +1,52 @@
+/* ============================================================================
+ * 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 { useColorMode } from "@docusaurus/theme-common";
+import useBaseUrl from "@docusaurus/useBaseUrl";
+import ThemedImage from "@theme/ThemedImage";
+
+export default function ApiLogo(props: any): React.JSX.Element | undefined {
+  const { colorMode } = useColorMode();
+  const { logo, darkLogo } = props;
+  const altText = () => {
+    if (colorMode === "dark") {
+      return darkLogo?.altText ?? logo?.altText;
+    }
+    return logo?.altText;
+  };
+  const lightLogoUrl = useBaseUrl(logo?.url);
+  const darkLogoUrl = useBaseUrl(darkLogo?.url);
+
+  if (logo && darkLogo) {
+    return (
+      <ThemedImage
+        alt={altText()}
+        sources={{
+          light: lightLogoUrl,
+          dark: darkLogoUrl,
+        }}
+        className="openapi__logo"
+      />
+    );
+  }
+  if (logo || darkLogo) {
+    return (
+      <ThemedImage
+        alt={altText()}
+        sources={{
+          light: lightLogoUrl ?? darkLogoUrl,
+          dark: lightLogoUrl ?? darkLogoUrl,
+        }}
+        className="openapi__logo"
+      />
+    );
+  }
+
+  return undefined;
+}

package/src/theme/ApiTabs/_ApiTabs.scss

@@ -0,0 +1,142 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+.openapi-tabs__container {
+  margin-left: -1px;
+}
+
+.openapi-tabs__response-header {
+  &.openapi-tabs__heading {
+    margin-bottom: 0;
+  }
+}
+
+.openapi-tabs__response-code-item {
+  border: 1px solid transparent;
+  margin-top: 0 !important;
+  margin-right: 0.5rem;
+  padding: 0.35rem 0.85rem;
+  border-radius: var(--ifm-global-radius);
+  font-weight: var(--ifm-font-weight-bold);
+  font-size: 12px;
+  transition: 300ms;
+  color: var(--ifm-font-color-secondary);
+
+  &.success.active {
+    background-color: var(--ifm-color-success);
+    color: var(--ifm-color-white);
+  }
+
+  &.danger.active {
+    background-color: var(--ifm-color-danger);
+    color: var(--ifm-color-white);
+  }
+
+  &.info.active {
+    background-color: var(--ifm-color-info);
+    color: var(--ifm-color-white);
+  }
+
+  &.active,
+  &:hover {
+    opacity: 1;
+  }
+
+  &:hover:not(.active) {
+    background-color: transparent;
+    border: 1px solid var(--ifm-toc-border-color);
+  }
+}
+
+.openapi-tabs__response-code-item:not(.active) {
+  opacity: 0.65;
+}
+
+.openapi-tabs__response-code-item:hover {
+  opacity: 1;
+}
+
+.openapi-tabs__response-code-item:last-child {
+  margin-right: 0 !important;
+}
+
+/* Open API Response Code Tabs */
+.openapi-tabs__response-header-section {
+  border-top: 1px solid var(--ifm-toc-border-color);
+  margin-top: 2rem;
+  padding-top: 2rem;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.openapi-tabs__response-container {
+  display: flex;
+  align-items: center;
+  max-width: 390px;
+  padding-left: 1rem;
+  overflow: hidden;
+}
+
+.openapi-tabs__response-list-container {
+  padding: 0 0.25rem;
+  overflow-y: hidden;
+  overflow-x: scroll;
+  scroll-behavior: smooth;
+  scrollbar-width: none;
+}
+
+.openapi-tabs__response-list-container::-webkit-scrollbar {
+  display: none;
+}
+
+/* Response Code Tabs - Colored Dots */
+.openapi-tabs__response-dot {
+  width: 12.5px;
+  height: 12.5px;
+  margin-right: 5px;
+  border-radius: 50%;
+}
+
+.openapi-tabs__response-schema-container {
+  max-width: 600px;
+}
+
+/* Tab Arrows */
+.openapi-tabs__arrow {
+  content: "";
+  height: 1.25rem;
+  width: 1.25rem;
+  border: none;
+  min-width: 1.25rem;
+  background: var(--ifm-menu-link-sublist-icon) 50% / 2rem 2rem;
+  filter: var(--ifm-menu-link-sublist-icon-filter);
+
+  &:hover {
+    cursor: pointer;
+  }
+
+  &.left {
+    transform: rotate(270deg);
+  }
+
+  &.right {
+    transform: rotate(90deg);
+  }
+}
+
+@media screen and (max-width: 500px) {
+  .openapi-tabs__response-header-section {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .openapi-tabs__response-container {
+    width: 100%;
+    margin-top: var(--ifm-spacing-vertical);
+    padding: 0;
+  }
+}