docusaurus-plugin-openapi-docs 1.0.1 → 1.0.4

package/lib/options.js

@@ -6,13 +6,42 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OptionsSchema = exports.DEFAULT_OPTIONS = void 0;
+exports.OptionsSchema = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
-exports.DEFAULT_OPTIONS = {
-    id: "default",
-    config: {},
-};
+const sidebarOptions = utils_validation_1.Joi.object({
+    groupPathsBy: utils_validation_1.Joi.string().valid("tag"),
+    categoryLinkSource: utils_validation_1.Joi.string().valid("tag", "info"),
+    customProps: utils_validation_1.Joi.object(),
+    sidebarCollapsible: utils_validation_1.Joi.boolean(),
+    sidebarCollapsed: utils_validation_1.Joi.boolean(),
+});
 exports.OptionsSchema = utils_validation_1.Joi.object({
-    id: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.id),
-    config: utils_validation_1.Joi.object().default(exports.DEFAULT_OPTIONS.config),
+    id: utils_validation_1.Joi.string().required(),
+    docPluginId: utils_validation_1.Joi.string().required(),
+    config: utils_validation_1.Joi.object()
+        .pattern(/^/, utils_validation_1.Joi.object({
+        specPath: utils_validation_1.Joi.string().required(),
+        outputDir: utils_validation_1.Joi.string().required(),
+        template: utils_validation_1.Joi.string(),
+        sidebarOptions: sidebarOptions,
+        version: utils_validation_1.Joi.string().when("versions", {
+            is: utils_validation_1.Joi.exist(),
+            then: utils_validation_1.Joi.required(),
+        }),
+        label: utils_validation_1.Joi.string().when("versions", {
+            is: utils_validation_1.Joi.exist(),
+            then: utils_validation_1.Joi.required(),
+        }),
+        baseUrl: utils_validation_1.Joi.string().when("versions", {
+            is: utils_validation_1.Joi.exist(),
+            then: utils_validation_1.Joi.required(),
+        }),
+        versions: utils_validation_1.Joi.object().pattern(/^/, utils_validation_1.Joi.object({
+            specPath: utils_validation_1.Joi.string().required(),
+            outputDir: utils_validation_1.Joi.string().required(),
+            label: utils_validation_1.Joi.string().required(),
+            baseUrl: utils_validation_1.Joi.string().required(),
+        })),
+    }))
+        .required(),
 });

package/lib/sidebars/index.d.ts

@@ -1,3 +1,4 @@
 import { ProcessedSidebar } from "@docusaurus/plugin-content-docs/src/sidebars/types";
+import { TagObject } from "../openapi/types";
 import type { SidebarOptions, APIOptions, ApiMetadata } from "../types";
-export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[]): ProcessedSidebar;
+export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[], docPath: string): ProcessedSidebar;

package/lib/sidebars/index.js

@@ -10,31 +10,34 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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 groupByTags(items, sidebarOptions, options) {
-    // TODO: Figure out how to handle these
-    // const intros = items.filter(isInfoItem).map((item) => {
-    //   return {
-    //     type: "link" as const,
-    //     label: item.title,
-    //     href: item.permalink,
-    //     docId: item.id,
-    //   };
-    // });
+function isInfoItem(item) {
+    return item.type === "info";
+}
+function groupByTags(items, sidebarOptions, options, tags, docPath) {
     const { outputDir } = options;
-    const { sidebarCollapsed, sidebarCollapsible, customProps } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
+    const infoItems = items.filter(isInfoItem);
+    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 tags = (0, uniq_1.default)(apiItems
+    const apiTags = (0, uniq_1.default)(apiItems
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
-    // TODO: optimize this or make it a function
-    const basePath = outputDir
-        .slice(outputDir.indexOf("/", 1))
-        .replace(/^\/+/g, "");
+    const basePath = docPath
+        ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
+        : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
     function createDocItem(item) {
         var _a, _b;
         const sidebar_label = item.frontMatter.sidebar_label;
@@ -42,7 +45,7 @@ function groupByTags(items, sidebarOptions, options) {
         const id = item.id;
         return {
             type: "doc",
-            id: `${basePath}/${item.id}`,
+            id: basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
             label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
             customProps: customProps,
             className: (0, clsx_1.default)({
@@ -51,11 +54,54 @@ function groupByTags(items, sidebarOptions, options) {
             }, item.api.method),
         };
     }
-    const tagged = tags
+    let rootIntroDoc = undefined;
+    if (infoItems.length === 1) {
+        const infoItem = infoItems[0];
+        const id = infoItem.id;
+        rootIntroDoc = {
+            type: "doc",
+            id: `${basePath}/${id}`,
+        };
+    }
+    const tagged = apiTags
         .map((tag) => {
+        // Map info object to tag
+        const taggedInfoObject = intros.find((i) => i.tags ? i.tags.includes(tag) : undefined);
+        const tagObject = tags.flat().find((t) => {
+            var _a;
+            return (_a = (tag === t.name || tag === t["x-displayName"])) !== null && _a !== void 0 ? _a : {
+                name: tag,
+                description: `${tag} Index`,
+            };
+        });
+        // TODO: perhaps move this into a getLinkConfig() function
+        let linkConfig = undefined;
+        if (taggedInfoObject !== undefined && categoryLinkSource === "info") {
+            linkConfig = {
+                type: "doc",
+                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}/${tagId}`,
+            };
+        }
+        // Default behavior
+        if (categoryLinkSource === undefined) {
+            linkConfig = {
+                type: "generated-index",
+                title: tag,
+                slug: "/category/" + (0, lodash_1.kebabCase)(tag),
+            };
+        }
         return {
             type: "category",
             label: tag,
+            link: linkConfig,
             collapsible: sidebarCollapsible,
             collapsed: sidebarCollapsed,
             items: apiItems
@@ -64,25 +110,35 @@ function groupByTags(items, sidebarOptions, options) {
         };
     })
         .filter((item) => item.items.length > 0); // Filter out any categories with no items.
-    // const untagged = [
-    //   // TODO: determine if needed and how
-    //   {
-    //     type: "category" as const,
-    //     label: "UNTAGGED",
-    //     // collapsible: options.sidebarCollapsible, TODO: add option
-    //     // collapsed: options.sidebarCollapsed, TODO: add option
-    //     items: apiItems
-    //       //@ts-ignore
-    //       .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-    //       .map(createDocItem),
-    //   },
-    // ];
-    return [...tagged];
+    // Handle items with no tag
+    const untaggedItems = apiItems
+        .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+        .map(createDocItem);
+    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(createDocItem),
+            },
+        ];
+    }
+    // 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];
 }
-function generateSidebarSlice(sidebarOptions, options, api) {
+function generateSidebarSlice(sidebarOptions, options, api, tags, docPath) {
     let sidebarSlice = [];
-    if (sidebarOptions.groupPathsBy === "tags") {
-        sidebarSlice = groupByTags(api, sidebarOptions, options);
+    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,31 @@
+"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.versionCrumb = exports.versionSelector = void 0;
+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;
+}
+exports.versionSelector = versionSelector;
+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;
+}
+exports.versionCrumb = versionCrumb;

package/lib/types.d.ts

@@ -1,8 +1,9 @@
-import type { Request } from "@paloaltonetworks/postman-collection";
-import { InfoObject, OperationObject, SecuritySchemeObject } from "./openapi/types";
+import type Request from "@paloaltonetworks/postman-collection";
+import { InfoObject, OperationObject, SecuritySchemeObject, TagObject } from "./openapi/types";
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
     id?: string;
+    docPluginId: string;
     config: {
         [key: string]: APIOptions;
     };
@@ -12,17 +13,40 @@ 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 {
     loadedApi: ApiMetadata[];
 }
-export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata;
+export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
 export interface ApiMetadataBase {
     sidebar?: string;
     previous?: ApiNavLink;
     next?: ApiNavLink;
     id: string;
     unversionedId: string;
+    infoId?: string;
+    infoPath?: string;
     title: string;
     description: string;
     source: string;
@@ -52,17 +76,17 @@ 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 declare type ApiInfo = InfoObject;
 export interface ApiNavLink {
     title: string;
     permalink: string;
 }
-export interface SidebarOptions {
-    groupPathsBy?: string;
-    customProps?: {
-        [key: string]: unknown;
-    };
-    sidebarCollapsible?: boolean;
-    sidebarCollapsed?: boolean;
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,21 +28,21 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.18",
-    "@docusaurus/types": "2.0.0-beta.18",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
+    "@docusaurus/types": "2.0.0-beta.21",
     "@types/fs-extra": "^9.0.13",
     "@types/json-schema": "^7.0.9",
     "@types/lodash": "^4.14.176",
-    "@types/postman-collection": "^3.5.7",
     "utility-types": "^3.10.0"
   },
   "dependencies": {
-    "@docusaurus/mdx-loader": "2.0.0-beta.18",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.18",
-    "@docusaurus/utils": "2.0.0-beta.18",
-    "@docusaurus/utils-validation": "2.0.0-beta.18",
+    "@docusaurus/mdx-loader": "2.0.0-beta.21",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.21",
+    "@docusaurus/utils": "2.0.0-beta.21",
+    "@docusaurus/utils-validation": "2.0.0-beta.21",
     "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
     "@paloaltonetworks/postman-collection": "^4.1.0",
+    "@redocly/openapi-core": "^1.0.0-beta.100",
     "@types/js-yaml": "^4.0.5",
     "@types/mustache": "^4.1.2",
     "chalk": "^4.1.2",
@@ -53,6 +53,7 @@
     "json-schema-merge-allof": "^0.8.1",
     "lodash": "^4.17.20",
     "mustache": "^4.2.0",
+    "swagger2openapi": "^7.0.8",
     "webpack": "^5.61.0"
   },
   "peerDependencies": {
@@ -61,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "27f594d26440ffe6f890b35c79847e065a96723e"
+  "gitHead": "0a590e8aaaff087d13adb7b4be75aa0112b9a2b5"
 }