docusaurus-plugin-openapi-docs 0.0.0-1000

package/src/markdown/createArrayBracket.ts

@@ -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 { create } from "./utils";
+
+export function createOpeningArrayBracket() {
+  return create("li", {
+    children: create("div", {
+      style: {
+        fontSize: "var(--ifm-code-font-size)",
+        opacity: "0.6",
+        marginLeft: "-.5rem",
+        paddingBottom: ".5rem",
+      },
+      children: ["Array ["],
+    }),
+  });
+}
+
+export function createClosingArrayBracket() {
+  return create("li", {
+    children: create("div", {
+      style: {
+        fontSize: "var(--ifm-code-font-size)",
+        opacity: "0.6",
+        marginLeft: "-.5rem",
+      },
+      children: ["]"],
+    }),
+  });
+}

package/src/markdown/createAuthentication.ts

@@ -0,0 +1,201 @@
+/* ============================================================================
+ * 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 { createDescription } from "./createDescription";
+import { create, guard } from "./utils";
+import { OAuthFlowObject, SecuritySchemeObject } from "../openapi/types";
+
+export function createAuthentication(securitySchemes: SecuritySchemeObject) {
+  if (!securitySchemes || !Object.keys(securitySchemes).length) return "";
+
+  const createAuthenticationTable = (securityScheme: any) => {
+    const { bearerFormat, flows, name, scheme, type, openIdConnectUrl } =
+      securityScheme;
+
+    const createSecuritySchemeTypeRow = () =>
+      create("tr", {
+        children: [
+          create("th", { children: "Security Scheme Type:" }),
+          create("td", { children: type }),
+        ],
+      });
+
+    const createOAuthFlowRows = () => {
+      const flowRows = Object.entries(flows).map(([flowType, flowObj]) => {
+        const { authorizationUrl, tokenUrl, refreshUrl, scopes } =
+          flowObj as OAuthFlowObject;
+
+        return create("tr", {
+          children: [
+            create("th", { children: `OAuth Flow (${flowType}):` }),
+            create("td", {
+              children: [
+                guard(tokenUrl, () =>
+                  create("div", { children: `Token URL: ${tokenUrl}` })
+                ),
+                guard(authorizationUrl, () =>
+                  create("div", {
+                    children: `Authorization URL: ${authorizationUrl}`,
+                  })
+                ),
+                guard(refreshUrl, () =>
+                  create("div", { children: `Refresh URL: ${refreshUrl}` })
+                ),
+                create("span", { children: "Scopes:" }),
+                create("ul", {
+                  children: Object.entries(scopes).map(([scope, description]) =>
+                    create("li", { children: `${scope}: ${description}` })
+                  ),
+                }),
+              ],
+            }),
+          ],
+        });
+      });
+
+      return flowRows.join("");
+    };
+
+    switch (type) {
+      case "apiKey":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  create("tr", {
+                    children: [
+                      create("th", { children: "Header parameter name:" }),
+                      create("td", { children: name }),
+                    ],
+                  }),
+                ],
+              }),
+            }),
+          ],
+        });
+      case "http":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  create("tr", {
+                    children: [
+                      create("th", { children: "HTTP Authorization Scheme:" }),
+                      create("td", { children: scheme }),
+                    ],
+                  }),
+                  guard(bearerFormat, () =>
+                    create("tr", {
+                      children: [
+                        create("th", { children: "Bearer format:" }),
+                        create("td", { children: bearerFormat }),
+                      ],
+                    })
+                  ),
+                ],
+              }),
+            }),
+          ],
+        });
+      case "oauth2":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  createOAuthFlowRows(),
+                ],
+              }),
+            }),
+          ],
+        });
+      case "openIdConnect":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  guard(openIdConnectUrl, () =>
+                    create("tr", {
+                      children: [
+                        create("th", { children: "OpenID Connect URL:" }),
+                        create("td", { children: openIdConnectUrl }),
+                      ],
+                    })
+                  ),
+                ],
+              }),
+            }),
+          ],
+        });
+      default:
+        return "";
+    }
+  };
+
+  const formatTabLabel = (key: string, type: string, scheme: string) => {
+    const formattedLabel = key
+      .replace(/(_|-)/g, " ")
+      .trim()
+      .replace(/\w\S*/g, (str) => str.charAt(0).toUpperCase() + str.substr(1))
+      .replace(/([a-z])([A-Z])/g, "$1 $2")
+      .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2");
+    const isOAuth = type === "oauth2";
+    const isApiKey = type === "apiKey";
+    const isHttpBasic = type === "http" && scheme === "basic";
+    const isHttpBearer = type === "http" && scheme === "bearer";
+    const isOpenId = type === "openIdConnect";
+
+    if (isOAuth) return `OAuth 2.0: ${key}`;
+    if (isApiKey) return `API Key: ${key}`;
+    if (isHttpBasic) return "HTTP: Basic Auth";
+    if (isHttpBearer) return "HTTP: Bearer Auth";
+    if (isOpenId) return `OpenID Connect: ${key}`;
+
+    return formattedLabel;
+  };
+
+  return create("div", {
+    children: [
+      create(
+        "Heading",
+        {
+          children: "Authentication",
+          id: "authentication",
+          as: "h2",
+          className: "openapi-tabs__heading",
+        },
+        { inline: true }
+      ),
+      create("SchemaTabs", {
+        className: "openapi-tabs__security-schemes",
+        children: Object.entries(securitySchemes).map(
+          ([schemeKey, schemeObj]) =>
+            create("TabItem", {
+              label: formatTabLabel(
+                schemeKey,
+                schemeObj.type,
+                schemeObj.scheme
+              ),
+              value: `${schemeKey}`,
+              children: [
+                createDescription(schemeObj.description),
+                createAuthenticationTable(schemeObj),
+              ],
+            })
+        ),
+      }),
+    ],
+    style: { marginBottom: "2rem" },
+  });
+}

package/src/markdown/createAuthorization.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 { create } from "./utils";
+
+export function createAuthorization(infoPath: string) {
+  if (!infoPath) return undefined;
+  return [create("SecuritySchemes", { infoPath: infoPath }), "\n\n"];
+}

package/src/markdown/createCallbackMethodEndpoint.ts

@@ -0,0 +1,19 @@
+/* ============================================================================
+ * 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 { create } from "./utils";
+
+export function createCallbackMethodEndpoint(method: String, path: String) {
+  return [
+    create("MethodEndpoint", {
+      method: method,
+      path: path,
+      context: "callback",
+    }),
+    "\n\n",
+  ];
+}

package/src/markdown/createCallbacks.ts

@@ -0,0 +1,101 @@
+/* ============================================================================
+ * 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 { createCallbackMethodEndpoint } from "./createCallbackMethodEndpoint";
+import { createDescription } from "./createDescription";
+import { createRequestBodyDetails } from "./createRequestBodyDetails";
+import { createStatusCodes } from "./createStatusCodes";
+import { create } from "./utils";
+import { MediaTypeObject } from "../openapi/types";
+import { ApiItem } from "../types";
+
+interface Props {
+  callbacks: ApiItem["callbacks"];
+}
+
+interface RequestBodyProps {
+  title: string;
+  body: {
+    content?: {
+      [key: string]: MediaTypeObject;
+    };
+    description?: string;
+    required?: boolean;
+  };
+}
+
+export function createCallbacks({ callbacks }: Props) {
+  if (callbacks === undefined) {
+    return undefined;
+  }
+
+  const callbacksNames = Object.keys(callbacks);
+  if (callbacksNames.length === 0) {
+    return undefined;
+  }
+
+  return create("div", {
+    children: [
+      create("div", {
+        className: "openapi__divider",
+      }),
+      create(
+        "Heading",
+        {
+          children: "Callbacks",
+          id: "callbacks",
+          as: "h2",
+          className: "openapi-tabs__heading",
+        },
+        { inline: true }
+      ),
+      create("OperationTabs", {
+        className: "openapi-tabs__operation",
+        children: callbacksNames.flatMap((name) => {
+          const path = Object.keys(callbacks[name])[0];
+          const methods = new Map([
+            ["delete", callbacks[name][path].delete],
+            ["get", callbacks[name][path].get],
+            ["head", callbacks[name][path].head],
+            ["options", callbacks[name][path].options],
+            ["patch", callbacks[name][path].patch],
+            ["post", callbacks[name][path].post],
+            ["put", callbacks[name][path].put],
+            ["trace", callbacks[name][path].trace],
+          ]);
+
+          return Array.from(methods).flatMap(([method, operationObject]) => {
+            if (!operationObject) return [];
+
+            const { description, requestBody, responses } = operationObject;
+
+            return [
+              create("TabItem", {
+                label: `${method.toUpperCase()} ${name}`,
+                value: `${method}-${name}`,
+                children: [
+                  createCallbackMethodEndpoint(method, path),
+                  // TODO: add `deprecation notice` when markdown support is added
+                  createDescription(description),
+                  createRequestBodyDetails({
+                    title: "Body",
+                    body: requestBody,
+                  } as RequestBodyProps),
+                  createStatusCodes({
+                    id: "callbacks-responses",
+                    label: "Callbacks Responses",
+                    responses,
+                  }),
+                ],
+              }),
+            ];
+          });
+        }),
+      }),
+    ],
+  });
+}

package/src/markdown/createContactInfo.ts

@@ -0,0 +1,41 @@
+/* ============================================================================
+ * 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 { create, guard } from "./utils";
+import { ContactObject } from "../openapi/types";
+
+export function createContactInfo(contact: ContactObject) {
+  if (!contact || !Object.keys(contact).length) return "";
+  const { name, url, email } = contact;
+
+  return create("div", {
+    style: {
+      display: "flex",
+      flexDirection: "column",
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "Contact",
+      }),
+      create("span", {
+        children: [
+          guard(name, () => `${name}: `),
+          guard(email, () => `[${email}](mailto:${email})`),
+        ],
+      }),
+      guard(url, () =>
+        create("span", {
+          children: ["URL: ", `[${url}](${url})`],
+        })
+      ),
+    ],
+  });
+}

package/src/markdown/createDeprecationNotice.ts

@@ -0,0 +1,31 @@
+/* ============================================================================
+ * 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 { clean, guard, Props, render } from "./utils";
+
+function createAdmonition({ children }: Props) {
+  return `:::caution deprecated\n\n${render(children)}\n\n:::`;
+}
+
+interface DeprecationNoticeProps {
+  deprecated?: boolean;
+  description?: string;
+}
+
+export function createDeprecationNotice({
+  deprecated,
+  description,
+}: DeprecationNoticeProps) {
+  return guard(deprecated, () =>
+    createAdmonition({
+      children:
+        description && description.length > 0
+          ? clean(description)
+          : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
+    })
+  );
+}

package/src/markdown/createDescription.ts

@@ -0,0 +1,12 @@
+/* ============================================================================
+ * 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 { clean } from "./utils";
+
+export function createDescription(description: string | undefined) {
+  return `\n\n${clean(description)}\n\n`;
+}

package/src/markdown/createDetails.ts

@@ -0,0 +1,16 @@
+/* ============================================================================
+ * 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 { create, Props } from "./utils";
+
+export function createDetails({ children, style, ...rest }: Props) {
+  return create("details", {
+    style: { ...style },
+    ...rest,
+    children,
+  });
+}

package/src/markdown/createDetailsSummary.ts

@@ -0,0 +1,16 @@
+/* ============================================================================
+ * 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 { create, Props } from "./utils";
+
+export function createDetailsSummary({ children, style, ...rest }: Props) {
+  return create("summary", {
+    style: { ...style },
+    ...rest,
+    children,
+  });
+}

package/src/markdown/createDownload.ts

@@ -0,0 +1,15 @@
+/* ============================================================================
+ * 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 { create, guard } from "./utils";
+
+export function createDownload(url: string | undefined) {
+  return guard(url, (url) => [
+    create("Export", { url: url, proxy: undefined }),
+    `\n\n`,
+  ]);
+}

package/src/markdown/createHeading.ts

@@ -0,0 +1,23 @@
+/* ============================================================================
+ * 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 { clean, create } from "./utils";
+
+export function createHeading(heading: string) {
+  return [
+    create(
+      "Heading",
+      {
+        children: clean(heading),
+        as: "h1",
+        className: "openapi__heading",
+      },
+      { inline: true }
+    ),
+    `\n\n`,
+  ];
+}

package/src/markdown/createLicense.ts

@@ -0,0 +1,34 @@
+/* ============================================================================
+ * 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 { create, guard } from "./utils";
+import { LicenseObject } from "../openapi/types";
+
+export function createLicense(license: LicenseObject) {
+  if (!license || !Object.keys(license).length) return "";
+  const { name, url } = license;
+
+  return create("div", {
+    style: {
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "License",
+      }),
+      guard(url, () =>
+        create("a", {
+          href: url,
+          children: name ?? url,
+        })
+      ),
+    ],
+  });
+}

package/src/markdown/createLogo.ts

@@ -0,0 +1,21 @@
+/* ============================================================================
+ * 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 { create, guard } from "./utils";
+import { LogoObject } from "../openapi/types";
+
+export function createLogo(
+  logo: LogoObject | undefined,
+  darkLogo: LogoObject | undefined
+) {
+  return guard(logo || darkLogo, () => [
+    create("ApiLogo", {
+      logo: logo,
+      darkLogo: darkLogo,
+    }),
+  ]);
+}

package/src/markdown/createMethodEndpoint.ts

@@ -0,0 +1,19 @@
+/* ============================================================================
+ * 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 { create } from "./utils";
+
+export function createMethodEndpoint(method: String, path: String) {
+  return [
+    create("MethodEndpoint", {
+      method: method,
+      path: path,
+      context: "endpoint",
+    }),
+    "\n\n",
+  ];
+}

package/src/markdown/createParamsDetails.ts

@@ -0,0 +1,22 @@
+/* ============================================================================
+ * 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 { create } from "./utils";
+import { ApiItem } from "../types";
+
+interface Props {
+  parameters: ApiItem["parameters"];
+}
+
+export function createParamsDetails({ parameters }: Props) {
+  return [
+    create("ParamsDetails", {
+      parameters: parameters,
+    }),
+    "\n\n",
+  ];
+}

package/src/markdown/createRequestBodyDetails.ts

@@ -0,0 +1,24 @@
+/* ============================================================================
+ * 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 { createRequestSchema } from "./createRequestSchema";
+import { MediaTypeObject } from "../openapi/types";
+
+interface Props {
+  title: string;
+  body: {
+    content?: {
+      [key: string]: MediaTypeObject;
+    };
+    description?: string;
+    required?: boolean;
+  };
+}
+
+export function createRequestBodyDetails({ title, body }: Props) {
+  return createRequestSchema({ title, body });
+}

package/src/markdown/createRequestHeader.ts

@@ -0,0 +1,24 @@
+/* ============================================================================
+ * 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 { create } from "./utils";
+
+export function createRequestHeader(header: string) {
+  return [
+    create(
+      "Heading",
+      {
+        children: header,
+        id: header.replace(" ", "-").toLowerCase(),
+        as: "h2",
+        className: "openapi-tabs__heading",
+      },
+      { inline: true }
+    ),
+    `\n\n`,
+  ];
+}