docusaurus-plugin-openapi-docs 1.0.1 → 1.0.4

package/src/types.ts

@@ -5,13 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-// @ts-ignore
-import type { Request } from "@paloaltonetworks/postman-collection";
+import type Request from "@paloaltonetworks/postman-collection";
 
 import {
   InfoObject,
   OperationObject,
   SecuritySchemeObject,
+  TagObject,
 } from "./openapi/types";
 
 export type {
@@ -22,6 +22,7 @@ export type {
 } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
   id?: string;
+  docPluginId: string;
   config: {
     [key: string]: APIOptions;
   };
@@ -32,6 +33,27 @@ export interface APIOptions {
   outputDir: string;
   template?: string;
   sidebarOptions?: SidebarOptions;
+  version?: string;
+  label?: string;
+  baseUrl?: string;
+  versions?: {
+    [key: string]: APIVersionOptions;
+  };
+}
+
+export interface SidebarOptions {
+  groupPathsBy?: string;
+  categoryLinkSource?: string;
+  customProps?: { [key: string]: unknown };
+  sidebarCollapsible?: boolean;
+  sidebarCollapsed?: boolean;
+}
+
+export interface APIVersionOptions {
+  specPath: string;
+  outputDir: string;
+  label: string;
+  baseUrl: string;
 }
 
 export interface LoadedContent {
@@ -39,7 +61,7 @@ export interface LoadedContent {
   // loadedDocs: DocPageMetadata[]; TODO: cleanup
 }
 
-export type ApiMetadata = ApiPageMetadata | InfoPageMetadata;
+export type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
 
 export interface ApiMetadataBase {
   sidebar?: string;
@@ -48,6 +70,8 @@ export interface ApiMetadataBase {
   //
   id: string; // TODO legacy versioned id => try to remove
   unversionedId: string; // TODO new unversioned id => try to rename to "id"
+  infoId?: string;
+  infoPath?: string;
   title: string;
   description: string;
   source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
@@ -80,6 +104,15 @@ export interface InfoPageMetadata extends ApiMetadataBase {
   type: "info";
   info: ApiInfo;
   markdown?: string;
+  securitySchemes?: {
+    [key: string]: SecuritySchemeObject;
+  };
+}
+
+export interface TagPageMetadata extends ApiMetadataBase {
+  type: "tag";
+  tag: TagObject;
+  markdown?: string;
 }
 
 export type ApiInfo = InfoObject;
@@ -88,10 +121,3 @@ export interface ApiNavLink {
   title: string;
   permalink: string;
 }
-
-export interface SidebarOptions {
-  groupPathsBy?: string;
-  customProps?: { [key: string]: unknown };
-  sidebarCollapsible?: boolean;
-  sidebarCollapsed?: boolean;
-}

package/lib/markdown/createFullWidthTable.d.ts

@@ -1,2 +0,0 @@
-import { Props } from "./utils";
-export declare function createFullWidthTable({ children, style, ...rest }: Props): string;

package/lib/markdown/createFullWidthTable.js

@@ -1,18 +0,0 @@
-"use strict";
-/* ============================================================================
- * 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.
- * ========================================================================== */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createFullWidthTable = void 0;
-const utils_1 = require("./utils");
-function createFullWidthTable({ children, style, ...rest }) {
-    return (0, utils_1.create)("table", {
-        style: { display: "table", width: "100%", ...style },
-        ...rest,
-        children,
-    });
-}
-exports.createFullWidthTable = createFullWidthTable;

package/lib/markdown/createParamsTable.d.ts

@@ -1,7 +0,0 @@
-import { ApiItem } from "../types";
-interface Props {
-    parameters: ApiItem["parameters"];
-    type: "path" | "query" | "header" | "cookie";
-}
-export declare function createParamsTable({ parameters, type }: Props): string | undefined;
-export {};

package/lib/markdown/createParamsTable.js

@@ -1,80 +0,0 @@
-"use strict";
-/* ============================================================================
- * 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.
- * ========================================================================== */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createParamsTable = void 0;
-const lodash_1 = require("lodash");
-const createDescription_1 = require("./createDescription");
-const createFullWidthTable_1 = require("./createFullWidthTable");
-const schema_1 = require("./schema");
-const utils_1 = require("./utils");
-function createParamsTable({ parameters, type }) {
-    if (parameters === undefined) {
-        return undefined;
-    }
-    const params = parameters.filter((param) => (param === null || param === void 0 ? void 0 : param.in) === type);
-    if (params.length === 0) {
-        return undefined;
-    }
-    return (0, createFullWidthTable_1.createFullWidthTable)({
-        children: [
-            (0, utils_1.create)("thead", {
-                children: (0, utils_1.create)("tr", {
-                    children: (0, utils_1.create)("th", {
-                        style: { textAlign: "left" },
-                        children: `${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`,
-                    }),
-                }),
-            }),
-            (0, utils_1.create)("tbody", {
-                children: params.map((param) => (0, utils_1.create)("tr", {
-                    children: (0, utils_1.create)("td", {
-                        children: [
-                            (0, utils_1.create)("code", { children: param.name }),
-                            (0, utils_1.guard)(param.schema, (schema) => (0, utils_1.create)("span", {
-                                style: { opacity: "0.6" },
-                                children: ` ${(0, schema_1.getSchemaName)(schema)}`,
-                            })),
-                            (0, utils_1.guard)(param.required, () => [
-                                (0, utils_1.create)("span", {
-                                    style: { opacity: "0.6" },
-                                    children: " — ",
-                                }),
-                                (0, utils_1.create)("strong", {
-                                    style: {
-                                        fontSize: "var(--ifm-code-font-size)",
-                                        color: "var(--openapi-required)",
-                                    },
-                                    children: " REQUIRED",
-                                }),
-                            ]),
-                            (0, utils_1.guard)((0, schema_1.getQualifierMessage)(param.schema), (message) => (0, utils_1.create)("div", {
-                                style: { marginTop: "var(--ifm-table-cell-padding)" },
-                                children: (0, createDescription_1.createDescription)(message),
-                            })),
-                            (0, utils_1.guard)(param.description, (description) => (0, utils_1.create)("div", {
-                                style: { marginTop: "var(--ifm-table-cell-padding)" },
-                                children: (0, createDescription_1.createDescription)(description),
-                            })),
-                            (0, utils_1.guard)(param.example, (example) => (0, utils_1.create)("div", {
-                                style: { marginTop: "var(--ifm-table-cell-padding)" },
-                                children: (0, lodash_1.escape)(`Example: ${example}`),
-                            })),
-                            (0, utils_1.guard)(param.examples, (examples) => (0, utils_1.create)("div", {
-                                style: { marginTop: "var(--ifm-table-cell-padding)" },
-                                children: Object.entries(examples).map(([k, v]) => (0, utils_1.create)("div", {
-                                    children: (0, lodash_1.escape)(`Example (${k}): ${v.value}`),
-                                })),
-                            })),
-                        ],
-                    }),
-                })),
-            }),
-        ],
-    });
-}
-exports.createParamsTable = createParamsTable;

package/lib/markdown/createRequestBodyTable.d.ts

@@ -1,6 +0,0 @@
-interface Props {
-    title: string;
-    body: any;
-}
-export declare function createRequestBodyTable({ title, body }: Props): string | undefined;
-export {};

package/lib/markdown/createSchemaTable.d.ts

@@ -1,14 +0,0 @@
-import { MediaTypeObject } from "../openapi/types";
-interface Props {
-    style?: any;
-    title: string;
-    body: {
-        content?: {
-            [key: string]: MediaTypeObject;
-        };
-        description?: string;
-        required?: boolean;
-    };
-}
-export declare function createSchemaTable({ title, body, ...rest }: Props): string | undefined;
-export {};

package/lib/markdown/createSchemaTable.js

@@ -1,217 +0,0 @@
-"use strict";
-/* ============================================================================
- * 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.
- * ========================================================================== */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSchemaTable = void 0;
-const createDescription_1 = require("./createDescription");
-const createFullWidthTable_1 = require("./createFullWidthTable");
-const schema_1 = require("./schema");
-const utils_1 = require("./utils");
-function resolveAllOf(allOf) {
-    // TODO: naive implementation (only supports objects, no directly nested allOf)
-    const properties = allOf.reduce((acc, cur) => {
-        if (cur.properties !== undefined) {
-            const next = { ...acc, ...cur.properties };
-            return next;
-        }
-        return acc;
-    }, {});
-    const required = allOf.reduce((acc, cur) => {
-        if (Array.isArray(cur.required)) {
-            const next = [...acc, ...cur.required];
-            return next;
-        }
-        return acc;
-    }, []);
-    return { properties, required };
-}
-function createRow({ name, schema, required }) {
-    return (0, utils_1.create)("tr", {
-        children: (0, utils_1.create)("td", {
-            children: [
-                (0, utils_1.create)("code", { children: name }),
-                (0, utils_1.create)("span", {
-                    style: { opacity: "0.6" },
-                    children: ` ${(0, schema_1.getSchemaName)(schema, true)}`,
-                }),
-                (0, utils_1.guard)(required, () => [
-                    (0, utils_1.create)("span", {
-                        style: { opacity: "0.6" },
-                        children: " — ",
-                    }),
-                    (0, utils_1.create)("strong", {
-                        style: {
-                            fontSize: "var(--ifm-code-font-size)",
-                            color: "var(--openapi-required)",
-                        },
-                        children: " REQUIRED",
-                    }),
-                ]),
-                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: (0, createDescription_1.createDescription)(message),
-                })),
-                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: (0, createDescription_1.createDescription)(description),
-                })),
-                createRows({ schema: schema }),
-            ],
-        }),
-    });
-}
-function createRows({ schema }) {
-    // object
-    if (schema.properties !== undefined) {
-        return (0, createFullWidthTable_1.createFullWidthTable)({
-            style: {
-                marginTop: "var(--ifm-table-cell-padding)",
-                marginBottom: "0px",
-            },
-            children: (0, utils_1.create)("tbody", {
-                children: Object.entries(schema.properties).map(([key, val]) => createRow({
-                    name: key,
-                    schema: val,
-                    required: Array.isArray(schema.required)
-                        ? schema.required.includes(key)
-                        : false,
-                })),
-            }),
-        });
-    }
-    // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
-    if (schema.allOf !== undefined) {
-        const { properties, required } = resolveAllOf(schema.allOf);
-        return (0, createFullWidthTable_1.createFullWidthTable)({
-            style: {
-                marginTop: "var(--ifm-table-cell-padding)",
-                marginBottom: "0px",
-            },
-            children: (0, utils_1.create)("tbody", {
-                children: Object.entries(properties).map(([key, val]) => createRow({
-                    name: key,
-                    schema: val,
-                    required: Array.isArray(required) ? required.includes(key) : false,
-                })),
-            }),
-        });
-    }
-    // array
-    if (schema.items !== undefined) {
-        return createRows({ schema: schema.items });
-    }
-    // primitive
-    return undefined;
-}
-function createRowsRoot({ schema }) {
-    // object
-    if (schema.properties !== undefined) {
-        return Object.entries(schema.properties).map(([key, val]) => createRow({
-            name: key,
-            schema: val,
-            required: Array.isArray(schema.required)
-                ? schema.required.includes(key)
-                : false,
-        }));
-    }
-    // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
-    if (schema.allOf !== undefined) {
-        const { properties, required } = resolveAllOf(schema.allOf);
-        return Object.entries(properties).map(([key, val]) => createRow({
-            name: key,
-            schema: val,
-            required: Array.isArray(required) ? required.includes(key) : false,
-        }));
-    }
-    // array
-    if (schema.items !== undefined) {
-        return (0, utils_1.create)("tr", {
-            children: (0, utils_1.create)("td", {
-                children: [
-                    (0, utils_1.create)("span", {
-                        style: { opacity: "0.6" },
-                        children: ` ${(0, schema_1.getSchemaName)(schema, true)}`,
-                    }),
-                    createRows({ schema: schema.items }),
-                ],
-            }),
-        });
-    }
-    // primitive
-    return (0, utils_1.create)("tr", {
-        children: (0, utils_1.create)("td", {
-            children: [
-                (0, utils_1.create)("span", {
-                    style: { opacity: "0.6" },
-                    children: ` ${schema.type}`,
-                }),
-                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: (0, createDescription_1.createDescription)(message),
-                })),
-                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: (0, createDescription_1.createDescription)(description),
-                })),
-            ],
-        }),
-    });
-}
-function createSchemaTable({ title, body, ...rest }) {
-    if (body === undefined || body.content === undefined) {
-        return undefined;
-    }
-    // TODO:
-    // NOTE: We just pick a random content-type.
-    // How common is it to have multiple?
-    const randomFirstKey = Object.keys(body.content)[0];
-    const firstBody = body.content[randomFirstKey].schema;
-    if (firstBody === undefined) {
-        return undefined;
-    }
-    // we don't show the table if there is no properties to show
-    if (firstBody.properties !== undefined) {
-        if (Object.keys(firstBody.properties).length === 0) {
-            return undefined;
-        }
-    }
-    return (0, createFullWidthTable_1.createFullWidthTable)({
-        ...rest,
-        children: [
-            (0, utils_1.create)("thead", {
-                children: (0, utils_1.create)("tr", {
-                    children: (0, utils_1.create)("th", {
-                        style: { textAlign: "left" },
-                        children: [
-                            `${title} `,
-                            (0, utils_1.guard)(body.required, () => [
-                                (0, utils_1.create)("span", {
-                                    style: { opacity: "0.6" },
-                                    children: " — ",
-                                }),
-                                (0, utils_1.create)("strong", {
-                                    style: {
-                                        fontSize: "var(--ifm-code-font-size)",
-                                        color: "var(--openapi-required)",
-                                    },
-                                    children: " REQUIRED",
-                                }),
-                            ]),
-                            (0, utils_1.create)("div", {
-                                children: (0, createDescription_1.createDescription)(body.description),
-                            }),
-                        ],
-                    }),
-                }),
-            }),
-            (0, utils_1.create)("tbody", {
-                children: createRowsRoot({ schema: firstBody }),
-            }),
-        ],
-    });
-}
-exports.createSchemaTable = createSchemaTable;

package/src/markdown/createFullWidthTable.ts

@@ -1,16 +0,0 @@
-/* ============================================================================
- * 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 createFullWidthTable({ children, style, ...rest }: Props) {
-  return create("table", {
-    style: { display: "table", width: "100%", ...style },
-    ...rest,
-    children,
-  });
-}

package/src/markdown/createParamsTable.ts

@@ -1,102 +0,0 @@
-/* ============================================================================
- * 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 { escape } from "lodash";
-
-import { ApiItem } from "../types";
-import { createDescription } from "./createDescription";
-import { createFullWidthTable } from "./createFullWidthTable";
-import { getQualifierMessage, getSchemaName } from "./schema";
-import { create, guard } from "./utils";
-
-interface Props {
-  parameters: ApiItem["parameters"];
-  type: "path" | "query" | "header" | "cookie";
-}
-
-export function createParamsTable({ parameters, type }: Props) {
-  if (parameters === undefined) {
-    return undefined;
-  }
-  const params = parameters.filter((param) => param?.in === type);
-  if (params.length === 0) {
-    return undefined;
-  }
-
-  return createFullWidthTable({
-    children: [
-      create("thead", {
-        children: create("tr", {
-          children: create("th", {
-            style: { textAlign: "left" },
-            children: `${
-              type.charAt(0).toUpperCase() + type.slice(1)
-            } Parameters`,
-          }),
-        }),
-      }),
-      create("tbody", {
-        children: params.map((param) =>
-          create("tr", {
-            children: create("td", {
-              children: [
-                create("code", { children: param.name }),
-                guard(param.schema, (schema) =>
-                  create("span", {
-                    style: { opacity: "0.6" },
-                    children: ` ${getSchemaName(schema)}`,
-                  })
-                ),
-                guard(param.required, () => [
-                  create("span", {
-                    style: { opacity: "0.6" },
-                    children: " — ",
-                  }),
-                  create("strong", {
-                    style: {
-                      fontSize: "var(--ifm-code-font-size)",
-                      color: "var(--openapi-required)",
-                    },
-                    children: " REQUIRED",
-                  }),
-                ]),
-                guard(getQualifierMessage(param.schema), (message) =>
-                  create("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: createDescription(message),
-                  })
-                ),
-                guard(param.description, (description) =>
-                  create("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: createDescription(description),
-                  })
-                ),
-                guard(param.example, (example) =>
-                  create("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: escape(`Example: ${example}`),
-                  })
-                ),
-                guard(param.examples, (examples) =>
-                  create("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: Object.entries(examples).map(([k, v]) =>
-                      create("div", {
-                        children: escape(`Example (${k}): ${v.value}`),
-                      })
-                    ),
-                  })
-                ),
-              ],
-            }),
-          })
-        ),
-      }),
-    ],
-  });
-}