DOP-3484: Suppress incompatible types warnings for Atlas Admin API (#754)

Author: rayangler

Dockerfile

@@ -25,7 +25,7 @@ ARG SNOOTY_PARSER_VERSION=0.13.16
 ARG SNOOTY_FRONTEND_VERSION=0.13.36
 # The Redoc CLI branch will most likely stay static. Updates to the branch should
 # be limited to CLI bug fixes and Redoc dependency version bumps
-ARG REDOC_CLI_VERSION=0.1.1
+ARG REDOC_CLI_VERSION=0.2.0
 ARG NPM_BASE_64_AUTH
 ARG NPM_EMAIL
 ENV DEBIAN_FRONTEND=noninteractive

modules/oas-page-builder/.eslintrc.js

@@ -16,6 +16,7 @@ module.exports = {
   },
   rules: {
     '@typescript-eslint/ban-ts-comment': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
     'no-console': 'off',
   },
 };

modules/oas-page-builder/src/services/pageBuilder.ts

@@ -2,7 +2,7 @@ import fetch from 'node-fetch';
 import { normalizePath } from '../utils/normalizePath';
 import { RedocExecutor } from './redocExecutor';
 import { findLastSavedGitHash } from './database';
-import { OASPageMetadata, PageBuilderOptions } from './types';
+import { OASPageMetadata, PageBuilderOptions, RedocBuildOptions } from './types';
 
 const OAS_FILE_SERVER = 'https://mongodb-mms-prod-build-server.s3.amazonaws.com/openapi/';
 
@@ -61,6 +61,7 @@ export const buildOpenAPIPages = async (
 
     try {
       let spec = '';
+      const buildOptions: RedocBuildOptions = {};
 
       if (sourceType === 'url') {
         spec = source;
@@ -69,12 +70,14 @@ export const buildOpenAPIPages = async (
         spec = localFilePath;
       } else if (sourceType === 'atlas') {
         spec = await getAtlasSpecUrl(source);
+        // Ignore "incompatible types" warnings for Atlas Admin API/cloud-docs
+        buildOptions['ignoreIncompatibleTypes'] = true;
       } else {
         throw new Error(`Unsupported source type "${sourceType}" for ${pageSlug}`);
       }
 
       const finalFilename = normalizePath(`${output}/${pageSlug}/index.html`);
-      await redocExecutor.execute(spec, finalFilename);
+      await redocExecutor.execute(spec, finalFilename, buildOptions);
     } catch (e) {
       console.error(e);
       // Continue to try to build other pages since it's possible that mut will

modules/oas-page-builder/src/services/redocExecutor.ts

@@ -1,30 +1,28 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { RedocBuildOptions } from './types';
 
 const execCommand = promisify(exec);
 
 export class RedocExecutor {
   redocPath: string;
-  // Stringified options object for Redoc command. Redoc also accepts individual options or a JSON file
-  private _optionsString: string;
+  // Options to be passed to Redoc build command
+  private options: Record<string, any>;
 
   constructor(redocPath: string, siteUrl: string, siteTitle: string) {
     this.redocPath = redocPath;
 
     // Custom options DOP defines in the Redoc fork
-    const customOptions = {
+    this.options = {
       backNavigationPath: siteUrl,
       siteTitle,
     };
-
-    // May contain both native Redoc options and custom DOP options in the future
-    this._optionsString = JSON.stringify({ customOptions });
   }
 
   // Calls Redoc CLI to build spec at given output path
-  async execute(specSource: string, outputPath: string) {
+  async execute(specSource: string, outputPath: string, buildOptions: RedocBuildOptions = {}) {
     const outputArg = `--output ${outputPath}`;
-    const optionsArg = `--options '${this._optionsString}'`;
+    const optionsArg = `--options '${this.finalizeOptions(buildOptions)}'`;
     const command = `node ${this.redocPath} build ${specSource} ${outputArg} ${optionsArg}`;
 
     const { stdout, stderr } = await execCommand(command);
@@ -35,4 +33,14 @@ export class RedocExecutor {
       throw stderr;
     }
   }
+
+  // Adds any additional options required for current page
+  private finalizeOptions(buildOptions: RedocBuildOptions = {}): string {
+    const options = {
+      ...this.options,
+      ...buildOptions,
+    };
+    // Stringify JSON object to avoid syntax error when passing object
+    return JSON.stringify(options);
+  }
 }

modules/oas-page-builder/src/services/types.ts

@@ -15,3 +15,5 @@ export interface BuildMetadata {
 export interface PageBuilderOptions extends Omit<ModuleOptions, 'bundle'> {
   siteTitle: string;
 }
+
+export type RedocBuildOptions = Record<string, any>;

modules/oas-page-builder/tests/unit/services/pageBuilder.test.ts

@@ -41,6 +41,10 @@ describe('pageBuilder', () => {
     siteUrl: 'https://mongodb.com/docs',
     siteTitle: 'Test Docs',
   };
+  const expectedAtlasBuildOptions = {
+    ignoreIncompatibleTypes: true,
+  };
+  const expectedDefaultBuildOptions = {};
 
   beforeEach(() => {
     // Reset mock to reset call count
@@ -69,17 +73,20 @@ describe('pageBuilder', () => {
     // Local
     expect(mockExecute).toBeCalledWith(
       `${testOptions.repo}/source${testEntries[0][1].source}`,
-      `${testOptions.output}/${testEntries[0][0]}/index.html`
+      `${testOptions.output}/${testEntries[0][0]}/index.html`,
+      expectedDefaultBuildOptions
     );
     // Url
     expect(mockExecute).toBeCalledWith(
       `${testEntries[1][1].source}`,
-      getExpectedOutputPath(testOptions.output, testEntries[1][0])
+      getExpectedOutputPath(testOptions.output, testEntries[1][0]),
+      expectedDefaultBuildOptions
     );
     // Atlas
     expect(mockExecute).toBeCalledWith(
       `https://mongodb-mms-prod-build-server.s3.amazonaws.com/openapi/${MOCKED_GIT_HASH}.json`,
-      getExpectedOutputPath(testOptions.output, testEntries[2][0])
+      getExpectedOutputPath(testOptions.output, testEntries[2][0]),
+      expectedAtlasBuildOptions
     );
   });
 
@@ -93,7 +100,8 @@ describe('pageBuilder', () => {
     await buildOpenAPIPages(testEntries, testOptions);
     expect(mockExecute).toBeCalledWith(
       `https://mongodb-mms-prod-build-server.s3.amazonaws.com/openapi/${LAST_SAVED_GIT_HASH}.json`,
-      getExpectedOutputPath(testOptions.output, testEntries[0][0])
+      getExpectedOutputPath(testOptions.output, testEntries[0][0]),
+      expectedAtlasBuildOptions
     );
   });
 

modules/oas-page-builder/tests/unit/services/redocExecutor.test.ts

@@ -8,21 +8,38 @@ cp.exec.mockImplementation((command: string, callback: (a: null, b: string) => v
 });
 
 describe('RedocExecutor', () => {
+  const testRedocPath = '/path/to/redoc/cli/index.js';
+  const testSiteUrl = 'https://mongodb.com/docs';
+  const testSiteTitle = 'Test Docs';
+  const testSpecSource = '/path/to/spec.json';
+  const testOutputPath = '/path/to/output/index.html';
+
   it('calls the Redoc build command with expected parameters', async () => {
-    const testRedocPath = '/path/to/redoc/cli/index.js';
-    const testSiteUrl = 'https://mongodb.com/docs';
-    const testSiteTitle = 'Test Docs';
     const redocExecutor = new RedocExecutor(testRedocPath, testSiteUrl, testSiteTitle);
-
-    const testSpecSource = '/path/to/spec.json';
-    const testOutputPath = '/path/to/output/index.html';
     await redocExecutor.execute(testSpecSource, testOutputPath);
 
     const expectedOptions = {
-      customOptions: {
-        backNavigationPath: testSiteUrl,
-        siteTitle: testSiteTitle,
-      },
+      backNavigationPath: testSiteUrl,
+      siteTitle: testSiteTitle,
+    };
+    const expectedCommand = `node ${testRedocPath} build ${testSpecSource} --output ${testOutputPath} --options '${JSON.stringify(
+      expectedOptions
+    )}'`;
+    expect(cp.exec).toBeCalledWith(expectedCommand, expect.anything());
+  });
+
+  it('accepts additional build options', async () => {
+    const redocExecutor = new RedocExecutor(testRedocPath, testSiteUrl, testSiteTitle);
+    const testBuildOptions = {
+      ignoreIncompatibleTypes: true,
+    };
+    await redocExecutor.execute(testSpecSource, testOutputPath, testBuildOptions);
+
+    // Options should be concatenated together
+    const expectedOptions = {
+      backNavigationPath: testSiteUrl,
+      siteTitle: testSiteTitle,
+      ignoreIncompatibleTypes: true,
     };
     const expectedCommand = `node ${testRedocPath} build ${testSpecSource} --output ${testOutputPath} --options '${JSON.stringify(
       expectedOptions