docusaurus-theme-openapi-docs 1.0.0

package/src/theme/ApiItem/index.tsx

@@ -0,0 +1,171 @@
+/* ============================================================================
+ * 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 ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
+import {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+  useWindowSize,
+} from "@docusaurus/theme-common";
+import DocBreadcrumbs from "@theme/DocBreadcrumbs";
+import type { Props, FrontMatter } from "@theme/DocItem";
+import DocItemFooter from "@theme/DocItemFooter";
+import DocPaginator from "@theme/DocPaginator";
+import DocVersionBadge from "@theme/DocVersionBadge";
+import DocVersionBanner from "@theme/DocVersionBanner";
+import Heading from "@theme/Heading";
+import MDXContent from "@theme/MDXContent";
+import TOC from "@theme/TOC";
+import TOCCollapsible from "@theme/TOCCollapsible";
+import clsx from "clsx";
+import type { ApiItem as ApiItemType } from "docusaurus-plugin-openapi-docs/lib/types";
+
+import styles from "./styles.module.css";
+
+let ApiDemoPanel = (_: { item: any }) => <div style={{ marginTop: "3.5em" }} />;
+if (ExecutionEnvironment.canUseDOM) {
+  ApiDemoPanel = require("@theme/ApiDemoPanel").default;
+}
+
+interface ApiFrontMatter extends FrontMatter {
+  readonly api?: ApiItemType;
+}
+
+function DocItemMetadata(props: Props): JSX.Element {
+  const { content: DocContent } = props;
+  const { metadata, frontMatter, assets } = DocContent;
+  const { keywords } = frontMatter;
+  const { description, title } = metadata;
+  const image = assets.image ?? frontMatter.image;
+
+  return <PageMetadata {...{ title, description, keywords, image }} />;
+}
+
+function DocItemContent(props: Props): JSX.Element {
+  const { content: DocContent } = props;
+  const { metadata, frontMatter } = DocContent;
+  const {
+    hide_title: hideTitle,
+    hide_table_of_contents: hideTableOfContents,
+    toc_min_heading_level: tocMinHeadingLevel,
+    toc_max_heading_level: tocMaxHeadingLevel,
+  } = frontMatter;
+  const { title } = metadata;
+
+  const { api } = frontMatter as ApiFrontMatter;
+
+  // We only add a title if:
+  // - user doesn't ask to hide it with front matter
+  // - the markdown content does not already contain a top-level h1 heading
+  const shouldAddTitle =
+    !hideTitle && typeof DocContent.contentTitle === "undefined";
+
+  const windowSize = useWindowSize();
+
+  const canRenderTOC =
+    !hideTableOfContents && DocContent.toc && DocContent.toc.length > 0;
+
+  const renderTocDesktop =
+    canRenderTOC && (windowSize === "desktop" || windowSize === "ssr");
+
+  return (
+    <div className="row">
+      <div className={clsx("col", !hideTableOfContents && styles.docItemCol)}>
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+
+            {canRenderTOC && (
+              <TOCCollapsible
+                toc={DocContent.toc}
+                minHeadingLevel={tocMinHeadingLevel}
+                maxHeadingLevel={tocMaxHeadingLevel}
+                className={clsx(
+                  ThemeClassNames.docs.docTocMobile,
+                  styles.tocMobile
+                )}
+              />
+            )}
+
+            <div
+              className={clsx(
+                ThemeClassNames.docs.docMarkdown,
+                "theme-api-markdown",
+                "markdown"
+              )}
+            >
+              {/*
+                Title can be declared inside md content or declared through
+                front matter and added manually. To make both cases consistent,
+                the added title is added under the same div.markdown block
+                See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+                */}
+              {shouldAddTitle && (
+                <header>
+                  <Heading as="h1">{title}</Heading>
+                </header>
+              )}
+              <MDXContent>
+                <div className="row">
+                  <div className={clsx("col", api ? "col--7" : "col--12")}>
+                    <DocContent />
+                  </div>
+                  {api && (
+                    <div className="col col--5">
+                      <ApiDemoPanel item={api} />
+                    </div>
+                  )}
+                </div>
+              </MDXContent>
+            </div>
+            <div
+              className={clsx(
+                "col",
+                api ? "col--7" : !canRenderTOC ? "col--9" : "col--12"
+              )}
+            >
+              <DocItemFooter {...props} />
+            </div>
+          </article>
+          <div
+            className={clsx(
+              "col",
+              api ? "col--7" : !canRenderTOC ? "col--9" : "col--12"
+            )}
+          >
+            <DocPaginator previous={metadata.previous} next={metadata.next} />
+          </div>
+        </div>
+      </div>
+      {renderTocDesktop && (
+        <div className="col col--3">
+          <TOC
+            toc={DocContent.toc}
+            minHeadingLevel={tocMinHeadingLevel}
+            maxHeadingLevel={tocMaxHeadingLevel}
+            className={ThemeClassNames.docs.docTocDesktop}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function DocItem(props: Props): JSX.Element {
+  const docHtmlClassName = `docs-doc-id-${props.content.metadata.unversionedId}`;
+  return (
+    <HtmlClassNameProvider className={docHtmlClassName}>
+      <DocItemMetadata {...props} />
+      <DocItemContent {...props} />
+    </HtmlClassNameProvider>
+  );
+}

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

@@ -0,0 +1,109 @@
+:root {
+  --openapi-required: var(--ifm-color-danger);
+}
+
+.apiItemContainer article > *:first-child,
+.apiItemContainer header + * {
+  margin-top: 0;
+}
+
+/* default markdown margins look really silly in a table */
+:global(.theme-api-markdown table *:last-child) {
+  margin-bottom: 0;
+}
+
+:global(.theme-api-markdown details) {
+  margin: unset;
+  max-width: 600px;
+  background-color: transparent;
+  color: var(--ifm-font-color-base);
+  padding: unset;
+  border: unset !important;
+  box-shadow: unset !important;
+  --docusaurus-details-decoration-color: var(--ifm-font-color-base);
+}
+
+:global(.theme-api-markdown details > div > div) {
+  padding-top: unset !important;
+  border-top: unset !important;
+}
+
+:global(.theme-api-markdown code) {
+  max-width: 600px;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+
+  /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
+  .tocMobile {
+    display: none;
+  }
+}
+
+:global(.theme-api-markdown details li) {
+  list-style: none;
+  padding-bottom: 5px;
+  padding-top: 5px;
+}
+
+:global(.theme-api-markdown details li:last-child) {
+  border-left: none;
+}
+
+:global(.theme-api-markdown details p) {
+  margin-bottom: 0;
+}
+
+:global(.theme-api-markdown li::before) {
+  position: absolute;
+  top: 10px;
+  left: 0;
+  width: 0.7rem; /* width of horizontal line */
+  height: 0.5rem; /* vertical position of line */
+  vertical-align: top;
+  border-bottom: thin solid var(--ifm-color-gray-500);
+  content: "";
+  display: inline-block;
+}
+
+:global(.theme-api-markdown details ul) {
+  padding-left: 0;
+  /* font-family: "Fira Mono", monospace; */
+  font-size: 14px;
+}
+
+:global(.theme-api-markdown h2) {
+  font-size: 2rem;
+}
+
+:global(.schemaItem) {
+  list-style: none;
+  position: relative;
+  margin: 0 !important;
+  padding: 5px 0 5px 1rem;
+  border-left: thin solid var(--ifm-color-gray-500) !important;
+}
+
+:global(.schemaItem:hover) {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+:global(.schemaItem:focus) {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+:global(.paramsItem:hover) {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+:global(.paramsItem:focus) {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+:global(.theme-api-markdown div[class^="collapsibleContent"]) {
+  margin-top: 0 !important;
+  padding-left: 2px;
+}

package/src/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/src/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/src/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/src/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);
+}