fix: update build docs command

Author: AlexVarchuk

packages/cli/src/commands/build-docs/index.ts

@@ -1,12 +1,12 @@
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { writeFileSync, mkdirSync } from 'node:fs';
-import { default as redoc } from 'redoc';
 import { performance } from 'node:perf_hooks';
-import { isAbsoluteUrl, logger } from '@redocly/openapi-core';
-import { getObjectOrJSON, getPageHTML } from './utils.js';
+import { isAbsoluteUrl, loadConfig, logger, bundle } from '@redocly/openapi-core';
+import { getObjectOrJSON, getPageHTML, hasSwaggerProperty } from './utils.js';
 import { getExecutionTime, getFallbackApisOrExit } from '../../utils/miscellaneous.js';
 import { exitWithError } from '../../utils/error.js';
+import { convertSwagger2OpenAPI } from 'redoc';
 
 import type { BuildDocsArgv } from './types.js';
 import type { CommandArgs } from '../../wrapper.js';
@@ -28,22 +28,33 @@ export const handlerBuildCommand = async ({
     disableGoogleFont: argv.disableGoogleFont,
     templateFileName: argv.template,
     templateOptions: argv.templateOptions || {},
-    redocOptions: getObjectOrJSON(argv.theme?.openapi, config.forAlias(alias)),
+    redocOptions: getObjectOrJSON(argv.openapi, config.forAlias(alias)),
   };
 
-  const redocCurrentVersion = packageJson.dependencies.redoc;
+  if (argv.redocVersion !== packageJson.dependencies.redoc) {
+    logger.warn(
+      `\n ⚠️  You are using a custom Redoc version (${argv.redocVersion}) for generating static HTML.`
+    );
+  }
+  const redocVersion = argv.redocVersion || packageJson.dependencies.redoc;
 
   try {
     const elapsed = getExecutionTime(startedAt);
+    const config = await loadConfig({ configPath: argv.config });
+    const {
+      bundle: { parsed },
+    } = await bundle({
+      config,
+      ref: isAbsoluteUrl(pathToApi) ? pathToApi : resolve(pathToApi),
+    });
+    const openapiDescription = hasSwaggerProperty(parsed) ? convertSwagger2OpenAPI(parsed) : parsed;
 
-    const api = await redoc.loadAndBundleSpec(
-      isAbsoluteUrl(pathToApi) ? pathToApi : resolve(pathToApi)
-    );
-    collectSpecData?.(api);
+    logger.info(`✅  OpenAPI definition loaded and bundled in [⏱ ${elapsed}].\n`);
+
+    collectSpecData?.(openapiDescription);
     const pageHTML = await getPageHTML(
-      api,
-      pathToApi,
-      { ...options, redocCurrentVersion },
+      openapiDescription,
+      { ...options, redocVersion },
       argv.config
     );
 

packages/cli/src/commands/build-docs/types.ts

@@ -7,9 +7,9 @@ export type BuildDocsOptions = {
   disableGoogleFont?: boolean;
   port?: number;
   templateFileName?: string;
-  templateOptions?: any;
+  templateOptions?: Record<string, unknown>;
   redocOptions?: any;
-  redocCurrentVersion: string;
+  redocVersion: string;
 };
 
 export type BuildDocsArgv = {
@@ -18,8 +18,7 @@ export type BuildDocsArgv = {
   title?: string;
   disableGoogleFont?: boolean;
   template?: string;
-  templateOptions: Record<string, any>;
-  theme: {
-    openapi: string | Record<string, unknown>;
-  };
+  templateOptions: Record<string, unknown>;
+  openapi: string | Record<string, unknown>;
+  redocVersion?: string;
 } & VerifyConfigOptions;

packages/cli/src/commands/build-docs/utils.ts

@@ -1,11 +1,10 @@
 import { createElement } from 'react';
-import { default as redoc } from 'redoc';
+import { Redoc, ServerStyleSheet } from 'redoc';
 import { renderToString } from 'react-dom/server';
-import { ServerStyleSheet } from 'styled-components';
 import { default as handlebars } from 'handlebars';
 import * as path from 'node:path';
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
-import { isAbsoluteUrl, logger } from '@redocly/openapi-core';
+import { logger } from '@redocly/openapi-core';
 import * as url from 'node:url';
 import { exitWithError } from '../../utils/error.js';
 
@@ -49,48 +48,55 @@ export function getObjectOrJSON(
 }
 
 export async function getPageHTML(
-  api: any,
-  pathToApi: string,
+  definition: any,
   {
     title,
     disableGoogleFont,
     templateFileName,
     templateOptions,
     redocOptions = {},
-    redocCurrentVersion,
+    redocVersion,
   }: BuildDocsOptions,
   configPath?: string
 ) {
   logger.info('Prerendering docs\n');
 
-  const apiUrl = redocOptions.specUrl || (isAbsoluteUrl(pathToApi) ? pathToApi : undefined);
-  const store = await redoc.createStore(api, apiUrl, redocOptions);
   const sheet = new ServerStyleSheet();
-
-  const html = renderToString(sheet.collectStyles(createElement(redoc.Redoc, { store })));
-  const state = await store.toJS();
-  const css = sheet.getStyleTags();
+  const html = renderToString(
+    sheet.collectStyles(
+      createElement(Redoc, {
+        store: {
+          options: redocOptions,
+          definition,
+        },
+        router: 'memory',
+        withCommonStyles: true,
+      })
+    )
+  );
 
   templateFileName = templateFileName
     ? templateFileName
     : redocOptions?.htmlTemplate
     ? path.resolve(configPath ? path.dirname(configPath) : '', redocOptions.htmlTemplate)
     : path.join(__internalDirname, './template.hbs');
   const template = handlebars.compile(readFileSync(templateFileName).toString());
+
   return template({
     redocHTML: `
-      <div id="redoc">${html || ''}</div>
-      <script>
-      ${`const __redoc_state = ${sanitizeJSONString(JSON.stringify(state))};` || ''}
-
-      var container = document.getElementById('redoc');
-      Redoc.${'hydrate(__redoc_state, container)'};
-
-      </script>`,
-    redocHead:
-      `<script src="https://cdn.redocly.com/redoc/v${redocCurrentVersion}/bundles/redoc.standalone.js"></script>` +
-      css,
-    title: title || api.info.title || 'ReDoc documentation',
+      <div id="redoc">${html}</div>
+      <script type="module">
+        import * as Redoc from "https://cdn.redocly.com/redoc/${redocVersion}/redoc.standalone.js";
+        const __redoc_store = ${JSON.stringify({
+          options: redocOptions,
+          definition,
+        })};
+        var container = document.getElementById('redoc');
+        Redoc.hydrate(__redoc_store, container);
+      </script>
+    `,
+    redocHead: sheet.getStyleTags(),
+    title: title || definition.info.title || 'ReDoc documentation',
     disableGoogleFont,
     templateOptions,
   });
@@ -109,3 +115,12 @@ export function escapeClosingScriptTag(str: string): string {
 export function escapeUnicode(str: string): string {
   return str.replace(/\u2028|\u2029/g, (m) => '\\u202' + (m === '\u2028' ? '8' : '9'));
 }
+
+export function hasSwaggerProperty(obj: unknown): obj is { swagger: string } & Record<string, any> {
+  if (typeof obj !== 'object' || obj === null) {
+    return false;
+  }
+
+  const candidate = obj as Record<string, any>;
+  return 'swagger' in candidate && typeof candidate.swagger === 'string';
+}

packages/cli/src/index.ts

@@ -578,13 +578,17 @@ yargs(hideBin(process.argv))
               'Path to handlebars page template, see https://github.com/Redocly/redocly-cli/blob/main/packages/cli/src/commands/build-docs/template.hbs for the example.',
             type: 'string',
           },
+          redocVersion: {
+            describe: 'Version of Redoc to use.',
+            type: 'string',
+          },
           templateOptions: {
             describe:
               'Additional options to pass to the template. Use dot notation, e.g. templateOptions.metaDescription',
           },
-          theme: {
+          openapi: {
             describe:
-              'Redoc theme.openapi configuration. Use dot notation, e.g. theme.openapi.nativeScrollbars',
+              'Redoc openapi configuration. Use dot notation, e.g. openapi.hideDownloadButtons',
           },
           config: {
             describe: 'Path to the config file.',
@@ -596,9 +600,9 @@ yargs(hideBin(process.argv))
             default: 'warn' as RuleSeverity,
           },
         })
-        .check((argv: any) => {
-          if (argv.theme && !argv.theme?.openapi)
-            throw Error('Invalid option: theme.openapi not set.');
+        .check((argv) => {
+          if (argv?.redocVersion && !argv.redocVersion.startsWith('3.'))
+            throw Error('Invalid option: redocVersion should be higher or equal to 3.0');
           return true;
         }),
     async (argv) => {