Merge branch 'main' into feature/i18n

Author: rohit-gohri

.changeset/small-pugs-laugh.md

@@ -0,0 +1,6 @@
+---
+'docusaurus-plugin-redoc': minor
+'redocusaurus': minor
+---
+
+Add support for auto-loading folder

packages/docusaurus-plugin-redoc/src/index.ts

@@ -21,6 +21,7 @@ import {
   PluginOptionSchema,
   PluginOptions,
   PluginOptionsWithDefault,
+  PluginDirectUsageOptions,
   DEFAULT_OPTIONS,
 } from './options';
 import type { SpecProps, ApiDocProps } from './types/common';
@@ -30,7 +31,7 @@ import { loadRedoclyConfig } from './loadRedoclyConfig';
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const version = require('../package.json').version;
 
-export { PluginOptions, loadRedoclyConfig };
+export { PluginOptions, PluginDirectUsageOptions, loadRedoclyConfig };
 
 export default function redocPlugin(
   context: LoadContext,
@@ -41,7 +42,7 @@ export default function redocPlugin(
 }> {
   const { baseUrl } = context.siteConfig;
   const options: PluginOptionsWithDefault = { ...DEFAULT_OPTIONS, ...opts };
-  const { debug, spec, url: downloadUrl, config } = options;
+  const { debug, spec, url: downloadUrl, config, themeId } = options;
 
   let url = downloadUrl;
   const isSpecFile = fs.existsSync(spec);
@@ -56,7 +57,6 @@ export default function redocPlugin(
     console.error('[REDOCUSAURUS_PLUGIN] Options:', options);
   }
 
-  const { themeId } = options;
   return {
     name: 'docusaurus-plugin-redoc',
     async loadContent() {
@@ -185,9 +185,6 @@ export default function redocPlugin(
       fs.writeFileSync(staticFile, bundledYaml);
     },
     getPathsToWatch() {
-      if (!isSpecFile) {
-        return [];
-      }
       return filesToWatch;
     },
   };

packages/docusaurus-plugin-redoc/src/options.ts

@@ -15,37 +15,47 @@ type LayoutProps = {
   };
 };
 
-export interface PluginOptions {
-  id?: string;
-  spec: string;
-  url?: string;
-  route?: string;
-  layout?: LayoutProps;
+/**
+ * Can pass only if directly using plugin.
+ * `redocusaurus` auto populates them
+ */
+export interface PluginDirectUsageOptions {
   debug?: boolean;
   themeId?: string;
   /**
    * Redocly config to bundle file
    * @see https://redocly.com/docs/cli/configuration/configuration-file/
    */
   config?: string | RawConfig;
+  layout?: LayoutProps;
+}
+
+export interface PluginOptions extends PluginDirectUsageOptions {
+  id?: string;
+  spec: string;
+  url?: string;
+  route?: string;
 }
 
 export interface PluginOptionsWithDefault extends PluginOptions {
   debug: boolean;
 }
 
-export const DEFAULT_OPTIONS: Omit<PluginOptionsWithDefault, 'spec'> = {
+export const DEFAULT_OPTIONS = {
   layout: {},
   debug: false,
-};
+} satisfies Omit<PluginOptions, 'spec'>;
 
 export const PluginOptionSchema = Joi.object<PluginOptions>({
+  // Direct Usage without redocusaurus preset
   id: Joi.string(),
-  spec: Joi.string(),
-  url: Joi.string().uri({ allowRelative: true }).optional(),
-  layout: Joi.any().default(DEFAULT_OPTIONS.layout),
   debug: Joi.boolean().default(DEFAULT_OPTIONS.debug),
-  route: Joi.string().uri({ relativeOnly: true }).optional(),
   config: Joi.any().optional(),
   themeId: Joi.string().optional(),
+
+  // Basic
+  spec: Joi.string(),
+  url: Joi.string().uri({ allowRelative: true }).optional(),
+  route: Joi.string().uri({ relativeOnly: true }).optional(),
+  layout: Joi.any().default(DEFAULT_OPTIONS.layout),
 });

packages/redocusaurus/src/index.ts

@@ -1,45 +1,76 @@
+import path from 'path';
 import type { LoadContext } from '@docusaurus/types';
+import { Globby, createSlugger } from '@docusaurus/utils';
 import type { PluginOptions } from 'docusaurus-plugin-redoc';
 import type { ThemeOptions } from 'docusaurus-theme-redoc';
+import type { PresetEntry, PresetOptions, SpecOptions } from './types';
 
-export interface PresetOptions {
-  id?: string;
-  debug?: boolean;
-  /**
-   * Path to the Redocly config file `redocly.yaml`
-   */
-  config?: string;
-  specs: PluginOptions[];
-  theme?: ThemeOptions;
-}
-
-export type PresetEntry = ['redocusaurus', PresetOptions];
+export type { PresetEntry, PresetOptions };
 
-export default function preset(
+export default async function preset(
   context: LoadContext,
   opts: PresetOptions = {
-    specs: [],
     theme: {},
   },
 ) {
-  let specsArray: PluginOptions[] = [];
-  const { debug = false, specs, theme = {}, config } = opts;
+  const { debug = false, openapi, specs, theme = {}, config } = opts;
   if (debug) {
     console.error('[REDOCUSAURUS] Options:', opts);
   }
 
-  if (Array.isArray(specs)) {
-    specsArray = specs;
-  } else if (specs) {
-    specsArray = [specs];
+  const id = opts.id ? `-${opts.id}` : '';
+  const themeId = `theme-redoc${id}`;
+  if (debug) {
+    console.error('[REDOCUSAURUS] ID Suffix:', id);
   }
 
-  if (debug) {
-    console.error('[REDOCUSAURUS] Specs:', specsArray);
+  const specsArray: SpecOptions[] = [];
+
+  if (specs) {
+    if (debug) {
+      console.error('[REDOCUSAURUS] Specs Files:', specs);
+    }
+    specsArray.push(...(Array.isArray(specs) ? specs : [specs]));
   }
-  const id = opts.id ? `-${opts.id}` : '';
-  const themeId = `theme-redoc${id}`;
+  if (!specs || openapi) {
+    // Load folder if no specs provided or folder specifically provided
+    const folder = openapi?.folder || 'openapi';
+    const resolvedFolder = path.resolve(folder);
+    if (debug) {
+      console.error('[REDOCUSAURUS] Loading Folder:', {
+        folder,
+        resolvedFolder,
+      });
+    }
+    const specFiles = await Globby([
+      `${folder}/**/*.openapi.{yaml,json}`,
+      `${folder}/**/openapi.{yaml,json}`,
+    ]);
+    if (debug) {
+      console.error('[REDOCUSAURUS] Found openapi files:', specFiles);
+    }
+    const slugger = createSlugger();
+    specsArray.push(
+      ...specFiles.map((specFile): SpecOptions => {
+        const spec = path.resolve(specFile);
+        const fileRoute = path
+          .relative(resolvedFolder, spec)
+          .replace(/(\/index)?\.openapi\.(yaml|json)$/, '')
+          .replace(/\/*$/, '');
 
+        const docRoute = `${openapi?.routeBasePath ?? ''}/${fileRoute}`;
+        return {
+          id: slugger.slug(fileRoute),
+          spec: spec,
+          route: docRoute,
+        };
+      }),
+    );
+  }
+
+  if (debug) {
+    console.error('[REDOCUSAURUS] All specs:', specsArray);
+  }
   const resolvedPreset: {
     themes: readonly (readonly [string, ThemeOptions])[];
     plugins: readonly (readonly [string, PluginOptions])[];

packages/redocusaurus/src/types.ts

@@ -0,0 +1,44 @@
+import type {
+  PluginOptions,
+  PluginDirectUsageOptions,
+} from 'docusaurus-plugin-redoc';
+import type { ThemeOptions } from 'docusaurus-theme-redoc';
+
+interface FolderOptions {
+  /**
+   * Default is `openapi`. This is similar to how
+   * Will load all YAML or JSON files in the folder
+   * that are named `openapi` or end with `.openapi`, like:
+   *   - `index.openapi.yaml`
+   *   - `swagger.openapi.yaml`
+   *   - `swagger.openapi.json`
+   */
+  folder?: string;
+  /**
+   * The path at which the files will be rendered,
+   * if the file is called `index.openapi.yaml` it will be rendered at base path itself
+   * Otherwise the name of the file path from the base folder will be used as the url path
+   */
+  routeBasePath?: string;
+}
+
+export type SpecOptions = Omit<PluginOptions, keyof PluginDirectUsageOptions>;
+
+export type PresetOptions = {
+  id?: string;
+  debug?: boolean;
+  /**
+   * Path to the Redocly config file `redocly.yaml`
+   * @see https://redocly.com/docs/cli/configuration/configuration-file/
+   */
+  config?: string;
+  specs?: SpecOptions[];
+  /**
+   * The folder is not going to be hot-reloaded
+   * but any changes to specs loaded at start will trigger live-reload
+   */
+  openapi?: FolderOptions;
+  theme?: Omit<ThemeOptions, 'id'>;
+};
+
+export type PresetEntry = ['redocusaurus', PresetOptions];

website/docusaurus.config.ts

@@ -45,38 +45,17 @@ const config: Config = {
       {
         debug: Boolean(process.env.DEBUG || process.env.CI),
         config: path.join(__dirname, 'redocly.yaml'),
+        openapi: {
+          folder: 'openapi',
+          routeBasePath: '/examples',
+        },
         specs: [
-          {
-            id: 'using-single-yaml',
-            spec: 'openapi/single-file/openapi.yaml',
-            route: '/examples/using-single-yaml/',
-          },
-          {
-            id: 'using-multi-file-yaml',
-            spec: 'openapi/multi-file/openapi.yaml',
-            route: '/examples/using-multi-file-yaml/',
-          },
-          {
-            id: 'using-swagger-json',
-            spec: 'openapi/swagger/swagger.json',
-            route: '/examples/using-swagger-json/',
-          },
           {
             id: 'using-remote-url',
             // Remote File
             spec: 'https://redocly.github.io/redoc/openapi.yaml',
             route: '/examples/using-remote-url/',
           },
-          {
-            id: 'using-custom-page',
-            spec: 'openapi/single-file/openapi.yaml',
-            // NOTE: no `route` passed, instead data used in custom React Component ('custom-page/index.jsx')
-          },
-          {
-            id: 'using-custom-layout',
-            spec: 'openapi/single-file/openapi.yaml',
-            // NOTE: no `route` passed, instead data used in custom React Component ('custom-layout/index.jsx')
-          },
         ],
         theme: {
           /**