docusaurus-plugin-openapi-docs 0.0.0-368 → 0.0.0-374

package/README.md

@@ -101,12 +101,12 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 
 `docusaurus-plugin-openapi-docs` can be configured with the following options:
 
-| Name             | Type     | Default | Description                                                                                                          |
-| ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
-| `specPath`       | `string` | `null`  | Designated 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.                                                                         |
-| `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.                     |
+| 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.                                                                                |
+| `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.                            |
 
 `sidebarOptions` can be configured with the following options:
 

package/lib/index.d.ts

@@ -1,4 +1,8 @@
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import type { PluginOptions, LoadedContent } from "./types";
 export declare function isURL(str: string): boolean;
-export default function pluginOpenAPI(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+declare function pluginOpenAPIDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+declare namespace pluginOpenAPIDocs {
+    var validateOptions: ({ options, validate }: any) => any;
+}
+export default pluginOpenAPIDocs;

package/lib/index.js

@@ -17,12 +17,13 @@ const chalk_1 = __importDefault(require("chalk"));
 const mustache_1 = require("mustache");
 const markdown_1 = require("./markdown");
 const openapi_1 = require("./openapi");
+const options_1 = require("./options");
 const sidebars_1 = __importDefault(require("./sidebars"));
 function isURL(str) {
     return /^(https?:)\/\//m.test(str);
 }
 exports.isURL = isURL;
-function pluginOpenAPI(context, options) {
+function pluginOpenAPIDocs(context, options) {
     let { config } = options;
     let { siteDir } = context;
     async function generateApiDocs(options) {
@@ -44,8 +45,7 @@ function pluginOpenAPI(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, // TODO: find a better way to handle null
-                options, loadedApi, tags);
+                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags);
                 const sidebarSliceTemplate = template
                     ? fs_1.default.readFileSync(template).toString()
                     : `module.exports = {{{slice}}};`;
@@ -214,7 +214,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         }));
     }
     return {
-        name: `docusaurus-plugin-openapi`,
+        name: `docusaurus-plugin-openapi-docs`,
         extendCli(cli) {
             cli
                 .command(`gen-api-docs`)
@@ -262,4 +262,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         },
     };
 }
-exports.default = pluginOpenAPI;
+exports.default = pluginOpenAPIDocs;
+pluginOpenAPIDocs.validateOptions = ({ options, validate }) => {
+    const validatedOptions = validate(options_1.OptionsSchema, options);
+    return validatedOptions;
+};

package/lib/options.d.ts

@@ -1,4 +1,2 @@
 import { Joi } from "@docusaurus/utils-validation";
-import type { PluginOptions } from "./types";
-export declare const DEFAULT_OPTIONS: PluginOptions;
 export declare const OptionsSchema: Joi.ObjectSchema<any>;

package/lib/options.js

@@ -6,13 +6,24 @@
  * 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({
+    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().default(exports.DEFAULT_OPTIONS.id),
-    config: utils_validation_1.Joi.object().default(exports.DEFAULT_OPTIONS.config),
+    id: 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,
+    }))
+        .required(),
 });

package/lib/sidebars/index.js

@@ -20,7 +20,7 @@ function isInfoItem(item) {
 }
 function groupByTags(items, sidebarOptions, options, tags) {
     const { outputDir } = options;
-    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, contentDocsPath, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
     const intros = infoItems.map((item) => {
@@ -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 = contentDocsPath
+        ? outputDir.split(contentDocsPath)[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)({

package/lib/types.d.ts

@@ -69,6 +69,7 @@ export interface ApiNavLink {
     permalink: string;
 }
 export interface SidebarOptions {
+    contentDocsPath?: string;
     groupPathsBy?: string;
     categoryLinkSource?: string;
     customProps?: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-368",
+  "version": "0.0.0-374",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "22c02a6463280203fe9437c891412b6fbf2cd274"
+  "gitHead": "1a04b6a59b6ba534893ee06fc0f19b9a90768988"
 }

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,7 +23,7 @@ export function isURL(str: string): boolean {
   return /^(https?:)\/\//m.test(str);
 }
 
-export default function pluginOpenAPI(
+export default function pluginOpenAPIDocs(
   context: LoadContext,
   options: PluginOptions
 ): Plugin<LoadedContent> {
@@ -57,7 +58,7 @@ 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
@@ -288,7 +289,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
   }
 
   return {
-    name: `docusaurus-plugin-openapi`,
+    name: `docusaurus-plugin-openapi-docs`,
 
     extendCli(cli): void {
       cli
@@ -339,3 +340,8 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
     },
   };
 }
+
+pluginOpenAPIDocs.validateOptions = ({ options, validate }: any) => {
+  const validatedOptions = validate(OptionsSchema, options);
+  return validatedOptions;
+};

package/src/options.ts

@@ -7,14 +7,26 @@
 
 import { Joi } from "@docusaurus/utils-validation";
 
-import type { PluginOptions } from "./types";
-
-export const DEFAULT_OPTIONS: PluginOptions = {
-  id: "default",
-  config: {},
-};
+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().default(DEFAULT_OPTIONS.id),
-  config: Joi.object().default(DEFAULT_OPTIONS.config),
+  id: Joi.string().required(),
+  config: Joi.object()
+    .pattern(
+      /^/,
+      Joi.object({
+        specPath: Joi.string().required(),
+        outputDir: Joi.string().required(),
+        template: Joi.string(),
+        sidebarOptions: sidebarOptions,
+      })
+    )
+    .required(),
 });

package/src/sidebars/index.ts

@@ -43,6 +43,7 @@ function groupByTags(
     sidebarCollapsible,
     customProps,
     categoryLinkSource,
+    contentDocsPath,
   } = sidebarOptions;
 
   const apiItems = items.filter(isApiItem);
@@ -63,10 +64,9 @@ function groupByTags(
       .filter((item): item is string => !!item)
   );
 
-  // TODO: optimize this or make it a function
-  const basePath = outputDir
-    .slice(outputDir.indexOf("/", 1))
-    .replace(/^\/+/g, "");
+  const basePath = contentDocsPath
+    ? outputDir.split(contentDocsPath!)[1].replace(/^\/+/g, "")
+    : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
 
   function createDocItem(item: ApiPageMetadata): SidebarItemDoc {
     const sidebar_label = item.frontMatter.sidebar_label;
@@ -74,7 +74,8 @@ function groupByTags(
     const id = item.id;
     return {
       type: "doc" as const,
-      id: `${basePath}/${item.id}`,
+      id:
+        basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
       label: (sidebar_label as string) ?? title ?? id,
       customProps: customProps,
       className: clsx(

package/src/types.ts

@@ -101,6 +101,7 @@ export interface ApiNavLink {
 }
 
 export interface SidebarOptions {
+  contentDocsPath?: string;
   groupPathsBy?: string;
   categoryLinkSource?: string;
   customProps?: { [key: string]: unknown };