docusaurus-plugin-openapi-docs 1.0.3 → 1.0.6

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(),
+    docsPluginId: 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,4 +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[], tags: TagObject[]): ProcessedSidebar;
+export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[], docPath: string): ProcessedSidebar;

package/lib/sidebars/index.js

@@ -18,8 +18,8 @@ function isApiItem(item) {
 function isInfoItem(item) {
     return item.type === "info";
 }
-function groupByTags(items, sidebarOptions, options, tags) {
-    const { outputDir } = options;
+function groupByTags(items, sidebarOptions, options, tags, docPath) {
+    const { outputDir, label } = options;
     const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
@@ -35,10 +35,9 @@ function groupByTags(items, sidebarOptions, options, tags) {
     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;
@@ -46,7 +45,7 @@ function groupByTags(items, sidebarOptions, options, tags) {
         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)({
@@ -96,7 +95,9 @@ function groupByTags(items, sidebarOptions, options, tags) {
             linkConfig = {
                 type: "generated-index",
                 title: tag,
-                slug: "/category/" + (0, lodash_1.kebabCase)(tag),
+                slug: label
+                    ? "/category/" + (0, lodash_1.kebabCase)(label) + "/" + (0, lodash_1.kebabCase)(tag)
+                    : "/category/" + (0, lodash_1.kebabCase)(tag),
             };
         }
         return {
@@ -136,10 +137,10 @@ function groupByTags(items, sidebarOptions, options, tags) {
     }
     return [...tagged, ...untagged];
 }
-function generateSidebarSlice(sidebarOptions, options, api, tags) {
+function generateSidebarSlice(sidebarOptions, options, api, tags, docPath) {
     let sidebarSlice = [];
     if (sidebarOptions.groupPathsBy === "tag") {
-        sidebarSlice = groupByTags(api, sidebarOptions, options, tags);
+        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

@@ -3,6 +3,7 @@ import { InfoObject, OperationObject, SecuritySchemeObject, TagObject } from "./
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
     id?: string;
+    docsPluginId: string;
     config: {
         [key: string]: APIOptions;
     };
@@ -12,6 +13,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 {
     loadedApi: ApiMetadata[];
@@ -68,12 +90,3 @@ export interface ApiNavLink {
     title: string;
     permalink: string;
 }
-export interface SidebarOptions {
-    groupPathsBy?: string;
-    categoryLinkSource?: 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.3",
+  "version": "1.0.6",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -36,6 +36,7 @@
     "utility-types": "^3.10.0"
   },
   "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^9.0.9",
     "@docusaurus/mdx-loader": "2.0.0-beta.21",
     "@docusaurus/plugin-content-docs": "2.0.0-beta.21",
     "@docusaurus/utils": "2.0.0-beta.21",
@@ -62,5 +63,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "618a438ec42148f525fb92cb11d291ce50d2ad06"
+  "gitHead": "ff7622e334e96e7f39b0daf5ef2cb17bfa832834"
 }

package/src/index.ts

@@ -15,6 +15,7 @@ import { render } from "mustache";
 
 import { createApiPageMD, createInfoPageMD, createTagPageMD } from "./markdown";
 import { readOpenapiFiles, processOpenapiFiles } from "./openapi";
+import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
 import type { PluginOptions, LoadedContent, APIOptions } from "./types";
 
@@ -22,12 +23,55 @@ export function isURL(str: string): boolean {
   return /^(https?:)\/\//m.test(str);
 }
 
-export default function pluginOpenAPI(
+export function getDocsData(
+  dataArray: any[],
+  filter: string
+): Object | undefined {
+  // eslint-disable-next-line array-callback-return
+  const filteredData = dataArray.filter((data) => {
+    if (data[0] === filter) {
+      return data[1];
+    }
+
+    // Search plugin-content-docs instances
+    if (data[0] === "@docusaurus/plugin-content-docs") {
+      const pluginId = data[1].id ? data[1].id : "default";
+      if (pluginId === filter) {
+        return data[1];
+      }
+    }
+  })[0];
+  if (filteredData) {
+    // Search presets, e.g. "classic"
+    if (filteredData[0] === filter) {
+      return filteredData[1].docs;
+    }
+
+    // Search plugin-content-docs instances
+    if (filteredData[0] === "@docusaurus/plugin-content-docs") {
+      const pluginId = filteredData[1].id ? filteredData[1].id : "default";
+      if (pluginId === filter) {
+        return filteredData[1];
+      }
+    }
+  }
+  return;
+}
+
+export default function pluginOpenAPIDocs(
   context: LoadContext,
   options: PluginOptions
 ): Plugin<LoadedContent> {
-  let { config } = options;
-  let { siteDir } = context;
+  const { config, docsPluginId } = options;
+  const { siteDir, siteConfig } = context;
+
+  // Get routeBasePath and path from plugin-content-docs or preset
+  const presets: any = siteConfig.presets;
+  const plugins: any = siteConfig.plugins;
+  const presetsPlugins = presets.concat(plugins);
+  const docData: any = getDocsData(presetsPlugins, docsPluginId);
+  const docRouteBasePath = docData ? docData.routeBasePath : undefined;
+  const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
   async function generateApiDocs(options: APIOptions) {
     let { specPath, outputDir, template, sidebarOptions } = options;
@@ -37,7 +81,7 @@ export default function pluginOpenAPI(
       : path.resolve(siteDir, specPath);
 
     try {
-      const openapiFiles = await readOpenapiFiles(contentPath, {});
+      const openapiFiles = await readOpenapiFiles(contentPath, options);
       const [loadedApi, tags] = await processOpenapiFiles(
         openapiFiles,
         sidebarOptions!
@@ -57,10 +101,11 @@ export default function pluginOpenAPI(
       // TODO: figure out better way to set default
       if (Object.keys(sidebarOptions ?? {}).length > 0) {
         const sidebarSlice = generateSidebarSlice(
-          sidebarOptions!, // TODO: find a better way to handle null
+          sidebarOptions!,
           options,
           loadedApi,
-          tags
+          tags,
+          docPath
         );
 
         const sidebarSliceTemplate = template
@@ -163,7 +208,13 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         item.markdown = markdown;
         if (item.type === "api") {
           item.json = JSON.stringify(item.api);
-          if (item.infoId) item.infoPath = `${outputDir}/${item.infoId}`;
+          let infoBasePath = `${outputDir}/${item.infoId}`;
+          if (docRouteBasePath) {
+            infoBasePath = `${docRouteBasePath}/${outputDir
+              .split(docPath!)[1]
+              .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+          }
+          if (item.infoId) item.infoPath = infoBasePath;
         }
 
         const view = render(mdTemplate, item);
@@ -254,9 +305,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
     const apiDir = path.join(siteDir, outputDir);
     const apiMdxFiles = await Globby(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
       cwd: path.resolve(apiDir),
+      deep: 1,
     });
     const sidebarFile = await Globby(["sidebar.js"], {
       cwd: path.resolve(apiDir),
+      deep: 1,
     });
     apiMdxFiles.map((mdx) =>
       fs.unlink(`${apiDir}/${mdx}`, (err) => {
@@ -287,21 +340,66 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
     );
   }
 
+  async function generateVersions(versions: object, outputDir: string) {
+    let versionsArray = [] as object[];
+    for (const [version, metadata] of Object.entries(versions)) {
+      versionsArray.push({
+        version: version,
+        label: metadata.label,
+        baseUrl: metadata.baseUrl,
+      });
+    }
+
+    const versionsJson = JSON.stringify(versionsArray, null, 2);
+    try {
+      fs.writeFileSync(`${outputDir}/versions.json`, versionsJson, "utf8");
+      console.log(
+        chalk.green(`Successfully created "${outputDir}/versions.json"`)
+      );
+    } catch (err) {
+      console.error(
+        chalk.red(`Failed to write "${outputDir}/versions.json"`),
+        chalk.yellow(err)
+      );
+    }
+  }
+
+  async function cleanVersions(outputDir: string) {
+    if (fs.existsSync(`${outputDir}/versions.json`)) {
+      fs.unlink(`${outputDir}/versions.json`, (err) => {
+        if (err) {
+          console.error(
+            chalk.red(`Cleanup failed for "${outputDir}/versions.json"`),
+            chalk.yellow(err)
+          );
+        } else {
+          console.log(
+            chalk.green(`Cleanup succeeded for "${outputDir}/versions.json"`)
+          );
+        }
+      });
+    }
+  }
+
   return {
-    name: `docusaurus-plugin-openapi`,
+    name: `docusaurus-plugin-openapi-docs`,
 
     extendCli(cli): void {
       cli
         .command(`gen-api-docs`)
-        .description(`Generates API Docs mdx and sidebars.`)
-        .usage(
-          "[options] <id key value in plugin config within docusaurus.config.js>"
+        .description(
+          `Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).`
         )
+        .usage("<id>")
         .arguments("<id>")
         .action(async (id) => {
           if (id === "all") {
             if (config[id]) {
-              console.error(chalk.red("Can't use id 'all' for API Doc."));
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs configuration key."
+                )
+              );
             } else {
               Object.keys(config).forEach(async function (key) {
                 await generateApiDocs(config[key]);
@@ -309,24 +407,91 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             }
           } else if (!config[id]) {
             console.error(
-              chalk.red(`ID ${id} does not exist in openapi-plugin config`)
+              chalk.red(`ID '${id}' does not exist in OpenAPI docs config.`)
             );
           } else {
             await generateApiDocs(config[id]);
           }
         });
 
+      cli
+        .command(`gen-api-docs:version`)
+        .description(
+          `Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).`
+        )
+        .usage("<id:version>")
+        .arguments("<id:version>")
+        .action(async (id) => {
+          const [parentId, versionId] = id.split(":");
+          const parentConfig = Object.assign({}, config[parentId]);
+
+          const version = parentConfig.version as string;
+          const label = parentConfig.label as string;
+          const baseUrl = parentConfig.baseUrl as string;
+
+          let parentVersion = {} as any;
+          parentVersion[version] = { label: label, baseUrl: baseUrl };
+
+          const { versions } = config[parentId] as any;
+          const mergedVersions = Object.assign(parentVersion, versions);
+
+          // Prepare for merge
+          delete parentConfig.versions;
+          delete parentConfig.version;
+          delete parentConfig.label;
+          delete parentConfig.baseUrl;
+
+          // TODO: handle when no versions are defined by version command is passed
+          if (versionId === "all") {
+            if (versions[id]) {
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs versions configuration key."
+                )
+              );
+            } else {
+              await generateVersions(mergedVersions, parentConfig.outputDir);
+              Object.keys(versions).forEach(async (key) => {
+                const versionConfig = versions[key];
+                const mergedConfig = {
+                  ...parentConfig,
+                  ...versionConfig,
+                };
+                await generateApiDocs(mergedConfig);
+              });
+            }
+          } else if (!versions[versionId]) {
+            console.error(
+              chalk.red(
+                `Version ID '${versionId}' does not exist in OpenAPI docs versions config.`
+              )
+            );
+          } else {
+            const versionConfig = versions[versionId];
+            const mergedConfig = {
+              ...parentConfig,
+              ...versionConfig,
+            };
+            await generateVersions(mergedVersions, parentConfig.outputDir);
+            await generateApiDocs(mergedConfig);
+          }
+        });
+
       cli
         .command(`clean-api-docs`)
-        .description(`Clears the Generated API Docs mdx and sidebars.`)
-        .usage(
-          "[options] <id key value in plugin config within docusaurus.config.js>"
+        .description(
+          `Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).`
         )
+        .usage("<id>")
         .arguments("<id>")
         .action(async (id) => {
           if (id === "all") {
             if (config[id]) {
-              console.error(chalk.red("Can't use id 'all' for API Doc."));
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs configuration key."
+                )
+              );
             } else {
               Object.keys(config).forEach(async function (key) {
                 await cleanApiDocs(config[key]);
@@ -336,6 +501,51 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             await cleanApiDocs(config[id]);
           }
         });
+
+      cli
+        .command(`clean-api-docs:version`)
+        .description(
+          `Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).`
+        )
+        .usage("<id:version>")
+        .arguments("<id:version>")
+        .action(async (id) => {
+          const [parentId, versionId] = id.split(":");
+          const { versions } = config[parentId] as any;
+
+          const parentConfig = Object.assign({}, config[parentId]);
+          delete parentConfig.versions;
+
+          if (versionId === "all") {
+            if (versions[id]) {
+              chalk.red(
+                "Can't use id 'all' for OpenAPI docs versions configuration key."
+              );
+            } else {
+              await cleanVersions(parentConfig.outputDir);
+              Object.keys(versions).forEach(async (key) => {
+                const versionConfig = versions[key];
+                const mergedConfig = {
+                  ...parentConfig,
+                  ...versionConfig,
+                };
+                await cleanApiDocs(mergedConfig);
+              });
+            }
+          } else {
+            const versionConfig = versions[versionId];
+            const mergedConfig = {
+              ...parentConfig,
+              ...versionConfig,
+            };
+            await cleanApiDocs(mergedConfig);
+          }
+        });
     },
   };
 }
+
+pluginOpenAPIDocs.validateOptions = ({ options, validate }: any) => {
+  const validatedOptions = validate(OptionsSchema, options);
+  return validatedOptions;
+};

package/src/markdown/createParamsDetails.ts

@@ -25,6 +25,8 @@ export function createParamsDetails({ parameters, type }: Props) {
   }
 
   return createDetails({
+    "data-collapsed": false,
+    open: true,
     style: { marginBottom: "1rem" },
     children: [
       createDetailsSummary({

package/src/markdown/createSchemaDetails.ts

@@ -269,6 +269,8 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
   }
 
   return createDetails({
+    "data-collapsed": false,
+    open: true,
     ...rest,
     children: [
       createDetailsSummary({

package/src/markdown/index.ts

@@ -59,7 +59,7 @@ export function createInfoPageMD({
 }: InfoPageMetadata) {
   return render([
     `import Tabs from "@theme/Tabs";\n`,
-    `import TabItem from "@theme/TabItem";\n`,
+    `import TabItem from "@theme/TabItem";\n\n`,
     createVersionBadge(version),
     `# ${escape(title)}\n\n`,
     createDescription(description),

package/src/openapi/openapi.test.ts

@@ -16,7 +16,7 @@ describe("openapi", () => {
     it("readOpenapiFiles", async () => {
       const results = await readOpenapiFiles(
         path.join(__dirname, "__fixtures__/examples"),
-        {}
+        { specPath: "./", outputDir: "./" }
       );
       const categoryMeta = results.find((x) =>
         x.source.endsWith("_category_.json")

package/src/openapi/openapi.ts

@@ -19,6 +19,7 @@ import { kebabCase } from "lodash";
 import { isURL } from "../index";
 import {
   ApiMetadata,
+  APIOptions,
   ApiPageMetadata,
   InfoPageMetadata,
   SidebarOptions,
@@ -247,8 +248,12 @@ interface OpenApiFiles {
 
 export async function readOpenapiFiles(
   openapiPath: string,
-  _options: {}
+  options: APIOptions
 ): Promise<OpenApiFiles[]> {
+  // TODO: determine if this should be an API option
+  // Forces the json-schema-ref-parser
+  const parseJsonRefs = true;
+
   if (!isURL(openapiPath)) {
     const stat = await fs.lstat(openapiPath);
     if (stat.isDirectory()) {
@@ -270,7 +275,8 @@ export async function readOpenapiFiles(
           // TODO: make a function for this
           const fullPath = path.join(openapiPath, source);
           const data = (await loadAndBundleSpec(
-            fullPath
+            fullPath,
+            parseJsonRefs
           )) as OpenApiObjectWithRef;
           return {
             source: fullPath, // This will be aliased in process.
@@ -281,7 +287,10 @@ export async function readOpenapiFiles(
       );
     }
   }
-  const data = (await loadAndBundleSpec(openapiPath)) as OpenApiObjectWithRef;
+  const data = (await loadAndBundleSpec(
+    openapiPath,
+    parseJsonRefs
+  )) as OpenApiObjectWithRef;
   return [
     {
       source: openapiPath, // This will be aliased in process.