update folder option to path to match classic preset

rohit-gohri · Mar 9, 2024 · c564c6e · c564c6e
1 parent 646c5e1
commit c564c6e
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 11 deletions.
diff --git a/packages/redocusaurus/src/index.ts b/packages/redocusaurus/src/index.ts
@@ -7,6 +7,11 @@ import type { PresetEntry, PresetOptions, SpecOptions } from './types';
 
 export type { PresetEntry, PresetOptions };
 
+const DEFAULT_OPENAPI_OPTIONS = {
+  path: 'openapi',
+  routeBasePath: '/api',
+} satisfies NonNullable<PresetOptions['openapi']>;
+
 export default async function preset(
   context: LoadContext,
   opts: PresetOptions = {
@@ -34,22 +39,29 @@ export default async function preset(
   }
   if (!specs || openapi) {
     // Load folder if no specs provided or folder specifically provided
-    const folder = openapi?.folder || 'openapi';
+    const { path: folder, routeBasePath } = {
+      ...DEFAULT_OPENAPI_OPTIONS,
+      ...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();
+    const baseRoute = routeBasePath.replace(/\/*$/, '');
     specsArray.push(
       ...specFiles.map((specFile): SpecOptions => {
         const spec = path.resolve(specFile);
@@ -58,7 +70,7 @@ export default async function preset(
           .replace(/(\/index)?\.openapi\.(yaml|json)$/, '')
           .replace(/\/*$/, '');
 
-        const docRoute = `${openapi?.routeBasePath ?? ''}/${fileRoute}`;
+        const docRoute = `${baseRoute}/${fileRoute}`;
         return {
           id: slugger.slug(fileRoute),
           spec: spec,

diff --git a/packages/redocusaurus/src/types.ts b/packages/redocusaurus/src/types.ts
@@ -6,17 +6,23 @@ import type { ThemeOptions } from 'docusaurus-theme-redoc';
 
 interface FolderOptions {
   /**
-   * Default is `openapi`. This is similar to how
+   * Path to the openapi specs directory on the file system, relative to site
+   * directory.
+   * @default openapi
    * 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`
+   * The folder is not going to be live-reloaded
+   * but any changes to specs loaded at start will be watched and will trigger live-reload
    */
-  folder?: string;
+  path?: 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
+   * URL route for the api docs section of your site. **DO NOT** include a
+   * trailing slash. Use `/` for shipping api docs without base path.
+   * @default /api
+   * 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;
@@ -33,10 +39,6 @@ export type PresetOptions = {
    */
   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'>;
 };

diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
@@ -27,6 +27,7 @@ const config: Config = {
         debug: Boolean(process.env.DEBUG || process.env.CI),
         theme: { customCss: [require.resolve('./src/custom.css')] },
         docs: {
+          path: 'docs',
           routeBasePath: '/docs',
           editUrl:
             'https://github.com/rohit-gohri/redocusaurus/edit/main/website/',
@@ -39,7 +40,7 @@ const config: Config = {
         debug: Boolean(process.env.DEBUG || process.env.CI),
         config: path.join(__dirname, 'redocly.yaml'),
         openapi: {
-          folder: 'openapi',
+          path: 'openapi',
           routeBasePath: '/examples',
         },
         specs: [