docusaurus-plugin-openapi-docs 0.0.0-379 → 0.0.0-382

package/README.md

@@ -103,14 +103,24 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 
 > Note: You may optionally configure a dedicated `@docusaurus/plugin-content-docs` instance for use with `docusaurus-theme-openapi-docs` by setting `docItemComponent` to `@theme/ApiItem`.
 
-### Plugin Configuration Options
+## Plugin Configuration Options
 
-`docusaurus-plugin-openapi-docs` can be configured with the following options:
+The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options:
+
+| Name          | Type     | Default | Description                                                                                                                                          |
+| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`          | `string` | `null`  | A unique document id.                                                                                                                                |
+| `docPluginId` | `string` | `null`  | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
+
+### config
+
+`config` can be configured with the following options:
 
 | Name             | Type     | Default | Description                                                                                                                 |
 | ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `specPath`       | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
 | `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
+| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
 | `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
 | `sidebarOptions` | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                            |
 | `version`        | `string` | `null`  | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`.                                           |

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import type { PluginOptions, LoadedContent } from "./types";
 export declare function isURL(str: string): boolean;
+export declare function getDocsData(dataArray: any[], filter: string): Object | undefined;
 declare function pluginOpenAPIDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
 declare namespace pluginOpenAPIDocs {
     var validateOptions: ({ options, validate }: any) => any;

package/lib/index.js

@@ -9,7 +9,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isURL = void 0;
+exports.getDocsData = exports.isURL = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
@@ -23,9 +23,46 @@ function isURL(str) {
     return /^(https?:)\/\//m.test(str);
 }
 exports.isURL = isURL;
+function getDocsData(dataArray, filter) {
+    // 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;
+}
+exports.getDocsData = getDocsData;
 function pluginOpenAPIDocs(context, options) {
-    let { config } = options;
-    let { siteDir } = context;
+    const { config, docPluginId } = options;
+    const { siteDir, siteConfig } = context;
+    // Get routeBasePath and path from plugin-content-docs or preset
+    const presets = siteConfig.presets;
+    const plugins = siteConfig.plugins;
+    const presetsPlugins = presets.concat(plugins);
+    const docData = getDocsData(presetsPlugins, docPluginId);
+    const docRouteBasePath = docData ? docData.routeBasePath : undefined;
+    const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     async function generateApiDocs(options) {
         let { specPath, outputDir, template, sidebarOptions } = options;
         const contentPath = isURL(specPath)
@@ -45,7 +82,7 @@ function pluginOpenAPIDocs(context, options) {
             }
             // TODO: figure out better way to set default
             if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
-                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags);
+                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath);
                 const sidebarSliceTemplate = template
                     ? fs_1.default.readFileSync(template).toString()
                     : `module.exports = {{{slice}}};`;
@@ -135,8 +172,14 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 item.markdown = markdown;
                 if (item.type === "api") {
                     item.json = JSON.stringify(item.api);
+                    let infoBasePath = `${outputDir}/${item.infoId}`;
+                    if (docRouteBasePath) {
+                        infoBasePath = `${docRouteBasePath}/${outputDir
+                            .split(docPath)[1]
+                            .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+                    }
                     if (item.infoId)
-                        item.infoPath = `${outputDir}/${item.infoId}`;
+                        item.infoPath = infoBasePath;
                 }
                 const view = (0, mustache_1.render)(mdTemplate, item);
                 const utils = (0, mustache_1.render)(infoMdTemplate, item);

package/lib/options.js

@@ -9,15 +9,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OptionsSchema = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const sidebarOptions = utils_validation_1.Joi.object({
-    contentDocsPath: utils_validation_1.Joi.string(),
     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(),
-}).with("groupPathsBy", "contentDocsPath");
+});
 exports.OptionsSchema = utils_validation_1.Joi.object({
     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(),

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,9 +18,9 @@ function isApiItem(item) {
 function isInfoItem(item) {
     return item.type === "info";
 }
-function groupByTags(items, sidebarOptions, options, tags) {
+function groupByTags(items, sidebarOptions, options, tags, docPath) {
     const { outputDir } = options;
-    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, contentDocsPath, } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
     const intros = infoItems.map((item) => {
@@ -35,8 +35,8 @@ function groupByTags(items, sidebarOptions, options, tags) {
     const apiTags = (0, uniq_1.default)(apiItems
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
-    const basePath = contentDocsPath
-        ? outputDir.split(contentDocsPath)[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;
@@ -135,10 +135,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/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;
+    docPluginId: string;
     config: {
         [key: string]: APIOptions;
     };
@@ -19,6 +20,15 @@ export interface APIOptions {
         [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;
@@ -80,13 +90,3 @@ export interface ApiNavLink {
     title: string;
     permalink: string;
 }
-export interface SidebarOptions {
-    contentDocsPath?: string;
-    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": "0.0.0-379",
+  "version": "0.0.0-382",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "87e5b6e59b66aae31c2f163060b030b232a45d39"
+  "gitHead": "b4ff3cdcca84c358bb0b55dd1f9704bc683b25b3"
 }

package/src/index.ts

@@ -23,12 +23,55 @@ export function isURL(str: string): boolean {
   return /^(https?:)\/\//m.test(str);
 }
 
+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, docPluginId } = 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, docPluginId);
+  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;
@@ -61,7 +104,8 @@ export default function pluginOpenAPIDocs(
           sidebarOptions!,
           options,
           loadedApi,
-          tags
+          tags,
+          docPath
         );
 
         const sidebarSliceTemplate = template
@@ -164,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);

package/src/options.ts

@@ -8,16 +8,16 @@
 import { Joi } from "@docusaurus/utils-validation";
 
 const sidebarOptions = Joi.object({
-  contentDocsPath: Joi.string(),
   groupPathsBy: Joi.string().valid("tag"),
   categoryLinkSource: Joi.string().valid("tag", "info"),
   customProps: Joi.object(),
   sidebarCollapsible: Joi.boolean(),
   sidebarCollapsed: Joi.boolean(),
-}).with("groupPathsBy", "contentDocsPath");
+});
 
 export const OptionsSchema = Joi.object({
   id: Joi.string().required(),
+  docPluginId: Joi.string().required(),
   config: Joi.object()
     .pattern(
       /^/,

package/src/sidebars/index.ts

@@ -35,7 +35,8 @@ function groupByTags(
   items: ApiPageMetadata[],
   sidebarOptions: SidebarOptions,
   options: APIOptions,
-  tags: TagObject[]
+  tags: TagObject[],
+  docPath: string
 ): ProcessedSidebar {
   const { outputDir } = options;
   const {
@@ -43,7 +44,6 @@ function groupByTags(
     sidebarCollapsible,
     customProps,
     categoryLinkSource,
-    contentDocsPath,
   } = sidebarOptions;
 
   const apiItems = items.filter(isApiItem);
@@ -64,8 +64,8 @@ function groupByTags(
       .filter((item): item is string => !!item)
   );
 
-  const basePath = contentDocsPath
-    ? outputDir.split(contentDocsPath!)[1].replace(/^\/+/g, "")
+  const basePath = docPath
+    ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
     : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
 
   function createDocItem(item: ApiPageMetadata): SidebarItemDoc {
@@ -184,7 +184,8 @@ export default function generateSidebarSlice(
   sidebarOptions: SidebarOptions,
   options: APIOptions,
   api: ApiMetadata[],
-  tags: TagObject[]
+  tags: TagObject[],
+  docPath: string
 ) {
   let sidebarSlice: ProcessedSidebar = [];
   if (sidebarOptions.groupPathsBy === "tag") {
@@ -192,7 +193,8 @@ export default function generateSidebarSlice(
       api as ApiPageMetadata[],
       sidebarOptions,
       options,
-      tags
+      tags,
+      docPath
     );
   }
   return sidebarSlice;

package/src/types.ts

@@ -22,6 +22,7 @@ export type {
 } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
   id?: string;
+  docPluginId: string;
   config: {
     [key: string]: APIOptions;
   };
@@ -40,6 +41,14 @@ export interface APIOptions {
   };
 }
 
+export interface SidebarOptions {
+  groupPathsBy?: string;
+  categoryLinkSource?: string;
+  customProps?: { [key: string]: unknown };
+  sidebarCollapsible?: boolean;
+  sidebarCollapsed?: boolean;
+}
+
 export interface APIVersionOptions {
   specPath: string;
   outputDir: string;
@@ -112,12 +121,3 @@ export interface ApiNavLink {
   title: string;
   permalink: string;
 }
-
-export interface SidebarOptions {
-  contentDocsPath?: string;
-  groupPathsBy?: string;
-  categoryLinkSource?: string;
-  customProps?: { [key: string]: unknown };
-  sidebarCollapsible?: boolean;
-  sidebarCollapsed?: boolean;
-}