docusaurus-theme-openapi-docs 0.0.0-345

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

package/src/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/src/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/src/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/src/types.ts

@@ -0,0 +1,70 @@
+/* ============================================================================
+ * 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 type { JSONSchema4, JSONSchema6, JSONSchema7 } from "json-schema";
+
+export interface ThemeConfig {
+  api?: {
+    proxy?: string;
+    authPersistance?: false | "localStorage" | "sessionStorage";
+  };
+}
+
+interface Map<T> {
+  [key: string]: T;
+}
+
+export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+export type SchemaObject = Omit<
+  JSONSchema,
+  | "type"
+  | "allOf"
+  | "oneOf"
+  | "anyOf"
+  | "not"
+  | "items"
+  | "properties"
+  | "additionalProperties"
+> & {
+  // OpenAPI specific overrides
+  type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
+  allOf?: SchemaObject[];
+  oneOf?: SchemaObject[];
+  anyOf?: SchemaObject[];
+  not?: SchemaObject;
+  items?: SchemaObject;
+  properties?: Map<SchemaObject>;
+  additionalProperties?: boolean | SchemaObject;
+
+  // OpenAPI additions
+  nullable?: boolean;
+  discriminator?: DiscriminatorObject;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  xml?: XMLObject;
+  externalDocs?: ExternalDocumentationObject;
+  example?: any;
+  deprecated?: boolean;
+};
+
+export interface DiscriminatorObject {
+  propertyName: string;
+  mapping?: Map<string>;
+}
+
+export interface XMLObject {
+  name?: string;
+  namespace?: string;
+  prefix?: string;
+  attribute?: boolean;
+  wrapped?: boolean;
+}
+
+export interface ExternalDocumentationObject {
+  description?: string;
+  url: string;
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["DOM", "ES2019"],
+    "module": "esnext",
+    "noEmit": true,
+    "jsx": "react"
+  },
+  "include": ["src"]
+}