docusaurus-theme-openapi-docs 1.0.0 → 1.0.3

package/package.json

@@ -1,18 +1,25 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "license": "MIT",
+  "keywords": [
+    "openapi",
+    "documentation",
+    "docusaurus",
+    "websites",
+    "theme"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi.git",
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs.git",
     "directory": "packages/docusaurus-theme-openapi-docs"
   },
   "bugs": {
-    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi/issues"
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues"
   },
   "types": "src/theme-openapi.d.ts",
   "main": "lib/index.js",
@@ -24,19 +31,18 @@
     "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",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
+    "@docusaurus/types": "2.0.0-beta.21",
     "@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/postman-collection": "^3.5.7",
     "@types/rtlcss": "^3.1.1",
     "concurrently": "^5.2.0"
   },
   "dependencies": {
-    "@docusaurus/theme-common": "^2.0.0-beta.18",
+    "@docusaurus/theme-common": "2.0.0-beta.21",
     "@mdx-js/react": "^1.6.21",
     "@monaco-editor/react": "^4.3.1",
     "@paloaltonetworks/postman-code-generators": "1.1.5-hotfix.5",
@@ -45,7 +51,7 @@
     "buffer": "^6.0.3",
     "clsx": "^1.1.1",
     "crypto-js": "^4.1.1",
-    "docusaurus-plugin-openapi-docs": "1.0.0",
+    "docusaurus-plugin-openapi-docs": "^1.0.3",
     "immer": "^9.0.7",
     "lodash": "^4.17.20",
     "monaco-editor": "^0.31.1",
@@ -64,5 +70,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "8905a438e86fc0a5cb9f033fb1b29630ff059af8"
+  "gitHead": "618a438ec42148f525fb92cb11d291ce50d2ad06"
 }

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/Curl/index.tsx

@@ -8,9 +8,7 @@
 import React, { useRef, useState, useEffect } from "react";
 
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
-// @ts-ignore
 import codegen from "@paloaltonetworks/postman-code-generators";
-// @ts-ignore
 import sdk from "@paloaltonetworks/postman-collection";
 import clsx from "clsx";
 import Highlight, { defaultProps } from "prism-react-renderer";

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

@@ -7,7 +7,6 @@
 
 import React, { useState } from "react";
 
-// @ts-ignore
 import MagicDropzone from "react-magic-dropzone";
 
 import FloatingButton from "../FloatingButton";

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

@@ -15,14 +15,16 @@ function colorForMethod(method: string) {
   switch (method.toLowerCase()) {
     case "get":
       return "primary";
-    case "put":
-      return "warning";
-    case "patch":
-      return "warning";
     case "post":
       return "success";
     case "delete":
       return "danger";
+    case "put":
+      return "info";
+    case "patch":
+      return "warning";
+    case "head":
+      return "secondary";
     default:
       return undefined;
   }

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

@@ -7,11 +7,14 @@
 
 import React from "react";
 
+import Link from "@docusaurus/Link";
+
 import { useTypedSelector } from "../hooks";
 
-function SecuritySchemes() {
+function SecuritySchemes(props: any) {
   const options = useTypedSelector((state) => state.auth.options);
   const selected = useTypedSelector((state) => state.auth.selected);
+  const infoAuthPath = `/${props.infoPath}#authentication`;
 
   if (selected === undefined) return null;
 
@@ -20,10 +23,17 @@ function SecuritySchemes() {
   return (
     <div style={{ marginBottom: "var(--ifm-table-cell-padding)" }}>
       {selectedAuth.map((auth) => {
-        if (auth.type === "apiKey") {
+        const isApiKey = auth.type === "apiKey";
+        const isBearer = auth.type === "http" && auth.key === "Bearer";
+        const isClientCredentials =
+          auth.type === "oauth2" && auth.key === "ClientCredentials";
+
+        if (isApiKey || isBearer) {
           return (
-            <React.Fragment key={selected + "-apiKey"}>
-              <b>Authorization: {auth.name}</b>
+            <React.Fragment key={selected}>
+              <b>
+                Authorization: <Link to={infoAuthPath}>{auth.key}</Link>
+              </b>
               <pre
                 style={{
                   display: "flex",
@@ -40,6 +50,24 @@ function SecuritySchemes() {
           );
         }
 
+        if (isClientCredentials) {
+          return (
+            <React.Fragment key={selected}>
+              <b>Authorization: {auth.key}</b>
+              <pre
+                style={{
+                  display: "flex",
+                  flexDirection: "column",
+                  background: "var(--openapi-card-background-color)",
+                  borderRadius: "var(--openapi-card-border-radius)",
+                }}
+              >
+                <span>type: {auth.type}</span>
+              </pre>
+            </React.Fragment>
+          );
+        }
+
         return null;
       })}
     </div>

package/src/theme/ApiDemoPanel/buildPostmanRequest.ts

@@ -9,9 +9,7 @@ import sdk from "@paloaltonetworks/postman-collection";
 import {
   ParameterObject,
   ServerObject,
-  // @ts-ignore
 } from "docusaurus-plugin-openapi-docs/src/openapi/types";
-// @ts-ignore
 import cloneDeep from "lodash/cloneDeep";
 
 import { AuthState, Scheme } from "./Authorization/slice";
@@ -250,6 +248,10 @@ function buildPostmanRequest(
     if (a.type === "http" && a.scheme === "bearer") {
       const { token } = auth.data[a.key];
       if (token === undefined) {
+        otherHeaders.push({
+          key: "Authorization",
+          value: "Bearer <TOKEN>",
+        });
         continue;
       }
       otherHeaders.push({
@@ -278,7 +280,7 @@ function buildPostmanRequest(
       if (apikey === undefined) {
         otherHeaders.push({
           key: a.name,
-          value: "API_KEY_VALUE",
+          value: "<API_KEY_VALUE>",
         });
         continue;
       }

package/src/theme/ApiDemoPanel/index.tsx

@@ -8,12 +8,9 @@
 import React from "react";
 
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
-// @ts-ignore
-// @ts-ignore
 import sdk from "@paloaltonetworks/postman-collection";
-// @ts-ignore
-import { Metadata } from "@theme/ApiItem";
 import { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 import { Provider } from "react-redux";
 
 import { ThemeConfig } from "../../types";
@@ -30,7 +27,13 @@ import Server from "./Server";
 import { createStoreWithState } from "./store";
 import styles from "./styles.module.css";
 
-function ApiDemoPanel({ item }: { item: NonNullable<Metadata["api"]> }) {
+function ApiDemoPanel({
+  item,
+  infoPath,
+}: {
+  item: NonNullable<ApiItem>;
+  infoPath: string;
+}) {
   const { siteConfig } = useDocusaurusContext();
   const themeConfig = siteConfig.themeConfig as ThemeConfig;
   const options = themeConfig.api;
@@ -39,8 +42,7 @@ function ApiDemoPanel({ item }: { item: NonNullable<Metadata["api"]> }) {
   const acceptArray = Array.from(
     new Set(
       Object.values(item.responses ?? {})
-        // @ts-ignore
-        .map((response) => Object.keys(response.content ?? {}))
+        .map((response: any) => Object.keys(response.content ?? {}))
         .flat()
     )
   );
@@ -58,10 +60,13 @@ function ApiDemoPanel({ item }: { item: NonNullable<Metadata["api"]> }) {
     cookie: [] as ParameterObject[],
   };
 
-  item.parameters?.forEach((param: { in: string | number }) => {
-    // @ts-ignore
-    params[param.in].push(param);
-  });
+  item.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: item.security,
@@ -90,9 +95,7 @@ function ApiDemoPanel({ item }: { item: NonNullable<Metadata["api"]> }) {
     <Provider store={store2}>
       <div className={styles.apiDemoPanelContainer}>
         <MethodEndpoint method={method} path={path} />
-
-        <SecuritySchemes />
-
+        <SecuritySchemes infoPath={infoPath} />
         <div className={styles.optionsPanel}>
           <ParamOptions />
           <Body
@@ -101,14 +104,11 @@ function ApiDemoPanel({ item }: { item: NonNullable<Metadata["api"]> }) {
           />
           <Accept />
         </div>
-
         <Server />
-
         <Curl
           postman={postman}
           codeSamples={(item as any)["x-code-samples"] ?? []}
         />
-
         <Response />
       </div>
     </Provider>

package/src/theme/ApiItem/index.tsx

@@ -15,7 +15,7 @@ import {
   useWindowSize,
 } from "@docusaurus/theme-common";
 import DocBreadcrumbs from "@theme/DocBreadcrumbs";
-import type { Props, FrontMatter } from "@theme/DocItem";
+import type { Props } from "@theme/DocItem";
 import DocItemFooter from "@theme/DocItemFooter";
 import DocPaginator from "@theme/DocPaginator";
 import DocVersionBadge from "@theme/DocVersionBadge";
@@ -27,14 +27,17 @@ import TOCCollapsible from "@theme/TOCCollapsible";
 import clsx from "clsx";
 import type { ApiItem as ApiItemType } from "docusaurus-plugin-openapi-docs/lib/types";
 
+import { DocFrontMatter } from "../../types";
 import styles from "./styles.module.css";
 
-let ApiDemoPanel = (_: { item: any }) => <div style={{ marginTop: "3.5em" }} />;
+let ApiDemoPanel = (_: { item: any; infoPath: any }) => (
+  <div style={{ marginTop: "3.5em" }} />
+);
 if (ExecutionEnvironment.canUseDOM) {
   ApiDemoPanel = require("@theme/ApiDemoPanel").default;
 }
 
-interface ApiFrontMatter extends FrontMatter {
+interface ApiFrontMatter extends DocFrontMatter {
   readonly api?: ApiItemType;
 }
 
@@ -52,11 +55,12 @@ function DocItemContent(props: Props): JSX.Element {
   const { content: DocContent } = props;
   const { metadata, frontMatter } = DocContent;
   const {
+    info_path: infoPath,
     hide_title: hideTitle,
     hide_table_of_contents: hideTableOfContents,
     toc_min_heading_level: tocMinHeadingLevel,
     toc_max_heading_level: tocMaxHeadingLevel,
-  } = frontMatter;
+  } = frontMatter as DocFrontMatter;
   const { title } = metadata;
 
   const { api } = frontMatter as ApiFrontMatter;
@@ -121,27 +125,17 @@ function DocItemContent(props: Props): JSX.Element {
                   </div>
                   {api && (
                     <div className="col col--5">
-                      <ApiDemoPanel item={api} />
+                      <ApiDemoPanel item={api} infoPath={infoPath} />
                     </div>
                   )}
                 </div>
               </MDXContent>
             </div>
-            <div
-              className={clsx(
-                "col",
-                api ? "col--7" : !canRenderTOC ? "col--9" : "col--12"
-              )}
-            >
+            <div className={clsx("col", api ? "col--7" : "col--12")}>
               <DocItemFooter {...props} />
             </div>
           </article>
-          <div
-            className={clsx(
-              "col",
-              api ? "col--7" : !canRenderTOC ? "col--9" : "col--12"
-            )}
-          >
+          <div className={clsx("col", api ? "col--7" : "col--12")}>
             <DocPaginator previous={metadata.previous} next={metadata.next} />
           </div>
         </div>

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

@@ -1,5 +1,9 @@
 :root {
   --openapi-required: var(--ifm-color-danger);
+  --openapi-code-blue: var(--ifm-color-info);
+  --openapi-code-red: var(--ifm-color-danger);
+  --openapi-code-orange: var(--ifm-color-warning);
+  --openapi-code-green: var(--ifm-color-success);
 }
 
 .apiItemContainer article > *:first-child,
@@ -75,9 +79,9 @@
   font-size: 14px;
 }
 
-:global(.theme-api-markdown h2) {
+/* :global(.theme-api-markdown h2) {
   font-size: 2rem;
-}
+} */
 
 :global(.schemaItem) {
   list-style: none;

package/{lib-next/theme/Tabs → src/theme/ApiTabs}/index.js

@@ -29,7 +29,7 @@ function isTabItem(comp) {
   return typeof comp.props.value !== "undefined";
 }
 
-function ResponseCodeTabs(props) {
+function ApiTabsComponent(props) {
   const {
     lazy,
     block,
@@ -246,10 +246,10 @@ function ResponseCodeTabs(props) {
   );
 }
 
-export default function Tabs(props) {
+export default function ApiTabs(props) {
   const isBrowser = useIsBrowser();
   return (
-    <ResponseCodeTabs // Remount tabs after hydration
+    <ApiTabsComponent // Remount tabs after hydration
       // Temporary fix for https://github.com/facebook/docusaurus/issues/5653
       key={String(isBrowser)}
       {...props}

package/src/types.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import type { FrontMatterTag } from "@docusaurus/utils";
 import type { JSONSchema4, JSONSchema6, JSONSchema7 } from "json-schema";
 
 export interface ThemeConfig {
@@ -68,3 +69,114 @@ export interface ExternalDocumentationObject {
   description?: string;
   url: string;
 }
+
+export type FileChange = {
+  author?: string;
+  /** Date can be any
+   * [parsable date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse).
+   */
+  date?: Date | string;
+};
+
+export type DocFrontMatter = {
+  /**
+   * The last part of the doc ID (will be refactored in the future to be the
+   * full ID instead)
+   * @see {@link DocMetadata.id}
+   */
+  id?: string;
+  /**
+   * Will override the default title collected from h1 heading.
+   * @see {@link DocMetadata.title}
+   */
+  title?: string;
+  /**
+   * Front matter tags, unnormalized.
+   * @see {@link DocMetadata.tags}
+   */
+  tags?: FrontMatterTag[];
+  /**
+   * If there isn't a Markdown h1 heading (which, if there is, we don't
+   * remove), this front matter will cause the front matter title to not be
+   * displayed in the doc page.
+   */
+  hide_title?: boolean;
+  /** Hide the TOC on the right. */
+  hide_table_of_contents?: boolean;
+  /** Used in the head meta. */
+  keywords?: string[];
+  /** Used in the head meta. Should use `assets.image` in priority. */
+  image?: string;
+  /**
+   * Will override the default excerpt.
+   * @see {@link DocMetadata.description}
+   */
+  description?: string;
+  /**
+   * Custom slug appended after /<baseUrl>/<routeBasePath>/<versionPath>
+   * @see {@link DocMetadata.slug}
+   */
+  slug?: string;
+  /** Customizes the sidebar label for this doc. Will default to its title. */
+  sidebar_label?: string;
+  /**
+   * Controls the position of a doc inside the generated sidebar slice when
+   * using autogenerated sidebar items.
+   *
+   * @see https://docusaurus.io/docs/sidebar#autogenerated-sidebar-metadata
+   */
+  sidebar_position?: number;
+  /**
+   * Gives the corresponding sidebar label a special class name when using
+   * autogenerated sidebars.
+   */
+  sidebar_class_name?: string;
+  /**
+   * Will be propagated to the final sidebars data structure. Useful if you
+   * have swizzled sidebar-related code or simply querying doc data through
+   * sidebars.
+   */
+  sidebar_custom_props?: { [key: string]: unknown };
+  /**
+   * Changes the sidebar association of the current doc. Use `null` to make
+   * the current doc not associated to any sidebar.
+   */
+  displayed_sidebar?: string | null;
+  /**
+   * Customizes the pagination label for this doc. Will default to the sidebar
+   * label.
+   */
+  pagination_label?: string;
+  /** Overrides the default URL computed for this doc. */
+  custom_edit_url?: string | null;
+  /**
+   * Whether number prefix parsing is disabled on this doc.
+   * @see https://docusaurus.io/docs/sidebar#using-number-prefixes
+   */
+  parse_number_prefixes?: boolean;
+  /**
+   * Minimum TOC heading level. Must be between 2 and 6 and lower or equal to
+   * the max value.
+   */
+  toc_min_heading_level?: number;
+  /** Maximum TOC heading level. Must be between 2 and 6. */
+  toc_max_heading_level?: number;
+  /**
+   * The ID of the documentation you want the "Next" pagination to link to.
+   * Use `null` to disable showing "Next" for this page.
+   * @see {@link DocMetadata.next}
+   */
+  pagination_next?: string | null;
+  /**
+   * The ID of the documentation you want the "Previous" pagination to link
+   * to. Use `null` to disable showing "Previous" for this page.
+   * @see {@link DocMetadata.prev}
+   */
+  pagination_prev?: string | null;
+  /** Should this doc be excluded from production builds? */
+  draft?: boolean;
+  /** Allows overriding the last updated author and/or date. */
+  last_update?: FileChange;
+  /** Provides OpenAPI Docs with a reference path to their respective Info Doc */
+  info_path?: string;
+};