docusaurus-plugin-openapi-docs 0.0.0-1000

package/lib/sidebars/index.js

@@ -0,0 +1,226 @@
+"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.
+ * ========================================================================== */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = generateSidebarSlice;
+const path_1 = __importDefault(require("path"));
+const utils_1 = require("@docusaurus/utils");
+const clsx_1 = __importDefault(require("clsx"));
+const lodash_1 = require("lodash");
+const uniq_1 = __importDefault(require("lodash/uniq"));
+function isApiItem(item) {
+    return item.type === "api";
+}
+function isInfoItem(item) {
+    return item.type === "info";
+}
+function isSchemaItem(item) {
+    return item.type === "schema";
+}
+const createDocItem = (item, { sidebarOptions: { customProps }, basePath }) => {
+    var _a, _b;
+    const sidebar_label = item.frontMatter.sidebar_label;
+    const title = item.title;
+    const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
+    const className = item.type === "api"
+        ? (0, clsx_1.default)({
+            "menu__list-item--deprecated": item.api.deprecated,
+            "api-method": !!item.api.method,
+        }, item.api.method)
+        : (0, clsx_1.default)({
+            "menu__list-item--deprecated": item.schema.deprecated,
+        }, "schema");
+    return {
+        type: "doc",
+        id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+        label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
+        customProps: customProps,
+        className: className ? className : undefined,
+    };
+};
+function groupByTags(items, sidebarOptions, options, tags, docPath) {
+    var _a, _b;
+    let { outputDir, label, showSchemas } = options;
+    // Remove trailing slash before proceeding
+    outputDir = outputDir.replace(/\/$/, "");
+    const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } = sidebarOptions;
+    const apiItems = items.filter(isApiItem);
+    const infoItems = items.filter(isInfoItem);
+    const schemaItems = items.filter(isSchemaItem);
+    const intros = infoItems.map((item) => {
+        return {
+            id: item.id,
+            title: item.title,
+            description: item.description,
+            tags: item.info.tags,
+        };
+    });
+    // TODO: make sure we only take the first tag
+    const operationTags = (0, uniq_1.default)(apiItems
+        .flatMap((item) => item.api.tags)
+        .filter((item) => !!item));
+    const schemaTags = (0, uniq_1.default)(schemaItems
+        .flatMap((item) => item.schema["x-tags"])
+        .filter((item) => !!item));
+    // Combine globally defined tags with operation and schema tags
+    // Only include global tag if referenced in operation/schema tags
+    let apiTags = [];
+    tags.flat().forEach((tag) => {
+        // Should we also check x-displayName?
+        if (operationTags.includes(tag.name) || schemaTags.includes(tag.name)) {
+            apiTags.push(tag.name);
+        }
+    });
+    if (sidebarOptions.groupPathsBy !== "tagGroup") {
+        apiTags = (0, uniq_1.default)(apiTags.concat(operationTags, schemaTags));
+    }
+    const basePath = docPath
+        ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
+        : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
+    const createDocItemFnContext = {
+        sidebarOptions,
+        basePath,
+    };
+    const createDocItemFn = (_b = (_a = sidebarOptions.sidebarGenerators) === null || _a === void 0 ? void 0 : _a.createDocItem) !== null && _b !== void 0 ? _b : createDocItem;
+    let rootIntroDoc = undefined;
+    if (infoItems.length === 1) {
+        const infoItem = infoItems[0];
+        const id = infoItem.id;
+        rootIntroDoc = {
+            type: "doc",
+            id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+        };
+    }
+    const tagged = apiTags
+        .map((tag) => {
+        var _a;
+        // Map info object to tag
+        const taggedInfoObject = intros.find((i) => i.tags ? i.tags.find((t) => t.name === tag) : undefined);
+        const tagObject = tags.flat().find((t) => tag === t.name && {
+            name: tag,
+            description: `${tag} Index`,
+        });
+        // TODO: perhaps move this into a getLinkConfig() function
+        // Default to no link config (spindowns only)
+        let linkConfig = undefined;
+        if (taggedInfoObject !== undefined && categoryLinkSource === "info") {
+            linkConfig = {
+                type: "doc",
+                id: basePath === "" || undefined
+                    ? `${taggedInfoObject.id}`
+                    : `${basePath}/${taggedInfoObject.id}`,
+            };
+        }
+        // TODO: perhaps move this into a getLinkConfig() function
+        if (tagObject !== undefined && categoryLinkSource === "tag") {
+            const tagId = (0, lodash_1.kebabCase)(tagObject.name);
+            linkConfig = {
+                type: "doc",
+                id: basePath === "" || undefined ? `${tagId}` : `${basePath}/${tagId}`,
+            };
+        }
+        if (categoryLinkSource === "auto") {
+            linkConfig = {
+                type: "generated-index",
+                title: tag,
+                slug: label
+                    ? (0, utils_1.posixPath)(path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(label), (0, lodash_1.kebabCase)(tag)))
+                    : (0, utils_1.posixPath)(path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(tag))),
+            };
+        }
+        const taggedApiItems = apiItems.filter((item) => { var _a; return !!((_a = item.api.tags) === null || _a === void 0 ? void 0 : _a.includes(tag)); });
+        const taggedSchemaItems = schemaItems.filter((item) => { var _a; return !!((_a = item.schema["x-tags"]) === null || _a === void 0 ? void 0 : _a.includes(tag)); });
+        return {
+            type: "category",
+            label: (_a = tagObject === null || tagObject === void 0 ? void 0 : tagObject["x-displayName"]) !== null && _a !== void 0 ? _a : tag,
+            link: linkConfig,
+            collapsible: sidebarCollapsible,
+            collapsed: sidebarCollapsed,
+            items: [...taggedSchemaItems, ...taggedApiItems].map((item) => createDocItemFn(item, createDocItemFnContext)),
+        };
+    })
+        .filter((item) => item.items.length > 0); // Filter out any categories with no items.
+    // Handle items with no tag
+    const untaggedItems = apiItems
+        .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+        .map((item) => createDocItemFn(item, createDocItemFnContext));
+    let untagged = [];
+    if (untaggedItems.length > 0) {
+        untagged = [
+            {
+                type: "category",
+                label: "UNTAGGED",
+                collapsible: sidebarCollapsible,
+                collapsed: sidebarCollapsed,
+                items: apiItems
+                    .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+                    .map((item) => createDocItemFn(item, createDocItemFnContext)),
+            },
+        ];
+    }
+    let schemas = [];
+    if (showSchemas && schemaItems.length > 0) {
+        schemas = [
+            {
+                type: "category",
+                label: "Schemas",
+                collapsible: sidebarCollapsible,
+                collapsed: sidebarCollapsed,
+                items: schemaItems
+                    .filter(({ schema }) => !schema["x-tags"])
+                    .map((item) => createDocItemFn(item, createDocItemFnContext)),
+            },
+        ];
+    }
+    // Shift root intro doc to top of sidebar
+    // TODO: Add input validation for categoryLinkSource options
+    if (rootIntroDoc && categoryLinkSource !== "info") {
+        tagged.unshift(rootIntroDoc);
+    }
+    return [...tagged, ...untagged, ...schemas];
+}
+function generateSidebarSlice(sidebarOptions, options, api, tags, docPath, tagGroups) {
+    let sidebarSlice = [];
+    if (sidebarOptions.groupPathsBy === "tagGroup") {
+        let schemasGroup = [];
+        tagGroups === null || tagGroups === void 0 ? void 0 : tagGroups.forEach((tagGroup) => {
+            var _a;
+            //filter tags only included in group
+            const filteredTags = [];
+            tags[0].forEach((tag) => {
+                if (tagGroup.tags.includes(tag.name)) {
+                    filteredTags.push(tag);
+                }
+            });
+            const groupCategory = {
+                type: "category",
+                label: tagGroup.name,
+                collapsible: true,
+                collapsed: true,
+                items: groupByTags(api, sidebarOptions, options, [filteredTags], docPath),
+            };
+            if (options.showSchemas) {
+                // For the first tagGroup, save the generated "Schemas" category for later.
+                if (schemasGroup.length === 0) {
+                    schemasGroup = (_a = groupCategory.items) === null || _a === void 0 ? void 0 : _a.filter((item) => item.type === "category" && item.label === "Schemas");
+                }
+                // Remove the "Schemas" category from every `groupCategory`.
+                groupCategory.items = groupCategory.items.filter((item) => "label" in item ? item.label !== "Schemas" : true);
+            }
+            sidebarSlice.push(groupCategory);
+        });
+        // Add `schemasGroup` to the end of the sidebar.
+        sidebarSlice.push(...schemasGroup);
+    }
+    else if (sidebarOptions.groupPathsBy === "tag") {
+        sidebarSlice = groupByTags(api, sidebarOptions, options, tags, docPath);
+    }
+    return sidebarSlice;
+}

package/lib/sidebars/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function versionSelector(versions: object[]): string;
+export declare function versionCrumb(version: string): string;

package/lib/sidebars/utils.js

@@ -0,0 +1,30 @@
+"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.versionSelector = versionSelector;
+exports.versionCrumb = versionCrumb;
+const mustache_1 = require("mustache");
+function versionSelector(versions) {
+    const template = `<div class="dropdown dropdown--hoverable dropdown--right">
+  <button class="button button--block button--sm button--secondary"><span>Select API Version</span></button>
+  <ul class="dropdown__menu">
+    {{#.}}<li><a class="dropdown__link" href="{{{baseUrl}}}">{{{label}}}</a></li>{{/.}}
+  </ul>
+</div>
+      `;
+    const view = (0, mustache_1.render)(template, versions);
+    return view;
+}
+function versionCrumb(version) {
+    const template = `<ul style="display: flex;" class="breadcrumbs breadcrumbs--sm">
+  <li style="margin-left: auto; margin-right: 0;" class="breadcrumbs__item breadcrumbs__item--active">
+  <a class="breadcrumbs__link"><span>{{{.}}}</span></a></li></ul>
+      `;
+    const view = (0, mustache_1.render)(template, version);
+    return view;
+}

package/lib/types.d.ts

@@ -0,0 +1,135 @@
+import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
+import type Request from "postman-collection";
+import { InfoObject, OperationObject, SchemaObject, SecuritySchemeObject, TagObject } from "./openapi/types";
+export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
+export interface PluginOptions {
+    id?: string;
+    docsPlugin?: string;
+    docsPluginId: string;
+    config: {
+        [key: string]: APIOptions;
+    };
+}
+export interface APIOptions {
+    specPath: string;
+    outputDir: string;
+    template?: string;
+    infoTemplate?: string;
+    tagTemplate?: string;
+    schemaTemplate?: string;
+    downloadUrl?: string;
+    hideSendButton?: boolean;
+    showExtensions?: boolean;
+    sidebarOptions?: SidebarOptions;
+    version?: string;
+    label?: string;
+    baseUrl?: string;
+    versions?: {
+        [key: string]: APIVersionOptions;
+    };
+    proxy?: string;
+    markdownGenerators?: MarkdownGenerator;
+    showSchemas?: boolean;
+    disableCompression?: boolean;
+}
+export interface MarkdownGenerator {
+    createApiPageMD?: (pageData: ApiPageMetadata) => string;
+    createInfoPageMD?: (pageData: InfoPageMetadata) => string;
+    createTagPageMD?: (pageData: TagPageMetadata) => string;
+    createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
+}
+export type ApiDocItemGenerator = (item: ApiPageMetadata | SchemaPageMetadata, context: {
+    sidebarOptions: SidebarOptions;
+    basePath: string;
+}) => SidebarItemDoc;
+export interface SidebarGenerators {
+    createDocItem?: ApiDocItemGenerator;
+}
+export interface SidebarOptions {
+    groupPathsBy?: string;
+    categoryLinkSource?: "info" | "tag" | "auto";
+    customProps?: {
+        [key: string]: unknown;
+    };
+    sidebarCollapsible?: boolean;
+    sidebarCollapsed?: boolean;
+    sidebarGenerators?: SidebarGenerators;
+}
+export interface APIVersionOptions {
+    specPath: string;
+    outputDir: string;
+    label: string;
+    baseUrl: string;
+    downloadUrl?: string;
+}
+export interface LoadedContent {
+    loadedApi: ApiMetadata[];
+}
+export type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata | SchemaPageMetadata;
+export interface ApiMetadataBase {
+    sidebar?: string;
+    previous?: ApiNavLink;
+    next?: ApiNavLink;
+    id: string;
+    unversionedId: string;
+    infoId?: string;
+    infoPath?: string;
+    downloadUrl?: string;
+    title: string;
+    description: string;
+    source: string;
+    sourceDirName: string;
+    slug?: string;
+    permalink: string;
+    sidebarPosition?: number;
+    frontMatter: Record<string, unknown>;
+    method?: string;
+    path?: string;
+}
+export interface ApiPageMetadata extends ApiMetadataBase {
+    json?: string;
+    type: "api";
+    api: ApiItem;
+    markdown?: string;
+}
+export interface ApiItem extends OperationObject {
+    method: string;
+    path: string;
+    jsonRequestBodyExample: string;
+    securitySchemes?: {
+        [key: string]: SecuritySchemeObject;
+    };
+    postman?: Request;
+    proxy?: string;
+    info: InfoObject;
+    extensions?: object;
+}
+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 interface SchemaPageMetadata extends ApiMetadataBase {
+    type: "schema";
+    schema: SchemaObject;
+    markdown?: string;
+}
+export interface TagGroupPageMetadata extends ApiMetadataBase {
+    type: "tagGroup";
+    name: string;
+    tags: TagObject[];
+    markdown?: string;
+}
+export type ApiInfo = InfoObject;
+export interface ApiNavLink {
+    title: string;
+    permalink: string;
+}

package/lib/types.js

@@ -0,0 +1,8 @@
+"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 });

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "docusaurus-plugin-openapi-docs",
+  "description": "OpenAPI plugin for Docusaurus.",
+  "version": "0.0.0-1000",
+  "license": "MIT",
+  "keywords": [
+    "openapi",
+    "documentation",
+    "docusaurus",
+    "websites",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs.git",
+    "directory": "packages/docusaurus-plugin-openapi-docs"
+  },
+  "bugs": {
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues"
+  },
+  "main": "lib/index.js",
+  "types": "src/plugin-openapi.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "devDependencies": {
+    "@docusaurus/plugin-content-docs": "^3.5.0",
+    "@docusaurus/types": "^3.5.0",
+    "@docusaurus/utils": "^3.5.0",
+    "@docusaurus/utils-validation": "^3.5.0",
+    "@types/fs-extra": "^9.0.13",
+    "@types/json-pointer": "^1.0.31",
+    "@types/json-schema": "^7.0.9",
+    "@types/lodash": "^4.14.176",
+    "@types/mustache": "^4.1.2",
+    "eslint-plugin-prettier": "^5.0.1"
+  },
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^11.5.4",
+    "@redocly/openapi-core": "^1.10.5",
+    "allof-merge": "^0.6.6",
+    "chalk": "^4.1.2",
+    "clsx": "^1.1.1",
+    "fs-extra": "^9.0.1",
+    "json-pointer": "^0.6.2",
+    "json5": "^2.2.3",
+    "lodash": "^4.17.20",
+    "mustache": "^4.2.0",
+    "openapi-to-postmanv2": "^4.21.0",
+    "postman-collection": "^4.4.0",
+    "slugify": "^1.6.5",
+    "swagger2openapi": "^7.0.8",
+    "xml-formatter": "^2.6.1"
+  },
+  "peerDependencies": {
+    "@docusaurus/plugin-content-docs": "^3.5.0",
+    "@docusaurus/utils": "^3.5.0",
+    "@docusaurus/utils-validation": "^3.5.0",
+    "react": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "gitHead": "abdd081aa1d8100eaed69342192f8d84fec853f7"
+}