feat(): routing platform independence (fastify-swagger options backwa…

…rd compatibility)
nestjs · Apr 13, 2022 · 472acc5 · 472acc5
1 parent ea85683
commit 472acc5
Show file tree

Hide file tree

Showing 5 changed files with 128 additions and 5 deletions.
diff --git a/e2e/manual-e2e.ts b/e2e/manual-e2e.ts
@@ -53,7 +53,7 @@ async function bootstrap() {
 
   SwaggerModule.setup('/swagger-docs', app, document, {
     customSiteTitle: 'Demo API - Swagger UI 2',
-    swaggerOptions: {
+    uiConfig: {
       persistAuthorization: true,
       defaultModelsExpandDepth: -1
     }

diff --git a/lib/interfaces/index.ts b/lib/interfaces/index.ts
@@ -1,3 +1,4 @@
 export { OpenAPIObject } from './open-api-spec.interface';
 export * from './swagger-custom-options.interface';
 export * from './swagger-document-options.interface';
+export * from './swagger-custom-options-legacy.instace';
diff --git a/lib/interfaces/swagger-custom-options-legacy.instace.ts b/lib/interfaces/swagger-custom-options-legacy.instace.ts
@@ -0,0 +1,67 @@
+interface _CommonSwaggerCustomOptions {
+  useGlobalPrefix?: boolean;
+}
+
+export interface ExpressSwaggerCustomOptions
+  extends _CommonSwaggerCustomOptions {
+  explorer?: boolean;
+  swaggerOptions?: Record<string, any>;
+  customCss?: string;
+  customCssUrl?: string;
+  customJs?: string;
+  customfavIcon?: string;
+  swaggerUrl?: string;
+  customSiteTitle?: string;
+  validatorUrl?: string;
+  url?: string;
+  urls?: Record<'url' | 'name', string>[];
+}
+
+/*
+ * @deprecated
+ */
+export interface FastifySwaggerCustomOptions
+  extends _CommonSwaggerCustomOptions {
+  uiConfig?: Partial<{
+    deepLinking: boolean;
+    displayOperationId: boolean;
+    defaultModelsExpandDepth: number;
+    defaultModelExpandDepth: number;
+    defaultModelRendering: string;
+    displayRequestDuration: boolean;
+    docExpansion: string;
+    filter: boolean | string;
+    layout: string;
+    maxDisplayedTags: number;
+    showExtensions: boolean;
+    showCommonExtensions: boolean;
+    useUnsafeMarkdown: boolean;
+    syntaxHighlight:
+      | {
+          activate?: boolean;
+          theme?: string;
+        }
+      | false;
+    tryItOutEnabled: boolean;
+    validatorUrl: string | null;
+    persistAuthorization: boolean;
+    tagsSorter: string;
+    operationsSorter: string;
+    queryConfigEnabled: boolean;
+  }>;
+  initOAuth?: Record<string, any>;
+  staticCSP?: boolean | string | Record<string, string | string[]>;
+  transformStaticCSP?: (header: string) => string;
+  uiHooks?: {
+    onRequest?: Function;
+    preHandler?: Function;
+  };
+}
+
+/*
+ * TODO: remove entire file when FastifySwaggerCustomOptions backward compatibility layer is no longer needed
+ *       and use SwaggerCustomOptions in SwaggerModule.setup
+ */
+export type SwaggerCustomOptionsLegacy =
+  | FastifySwaggerCustomOptions
+  | ExpressSwaggerCustomOptions;
diff --git a/lib/swagger-module.ts b/lib/swagger-module.ts
@@ -1,7 +1,7 @@
 import { INestApplication } from '@nestjs/common';
 import {
   OpenAPIObject,
-  SwaggerCustomOptions,
+  SwaggerCustomOptionsLegacy,
   SwaggerDocumentOptions
 } from './interfaces';
 import { SwaggerScanner } from './swagger-scanner';
@@ -16,6 +16,7 @@ import {
 } from './swagger-ui';
 import { NestFastifyApplication } from '@nestjs/platform-fastify';
 import { NestExpressApplication } from '@nestjs/platform-express';
+import { processSwaggerOptions } from './utils/backward-compatilibity-layer';
 
 export class SwaggerModule {
   public static createDocument(
@@ -98,7 +99,7 @@ export class SwaggerModule {
     path: string,
     app: INestApplication,
     document: OpenAPIObject,
-    options?: SwaggerCustomOptions
+    options?: SwaggerCustomOptionsLegacy
   ) {
     const globalPrefix = getGlobalPrefix(app);
     const finalPath = validatePath(
@@ -107,10 +108,14 @@ export class SwaggerModule {
         : path
     );
 
+    // START: fastify backward compatibility layer
+    const { customOptions, extra } = processSwaggerOptions(options);
+    // END: fastify backward compatibility layer
+
     const yamlDocument = jsyaml.dump(document);
     const jsonDocument = JSON.stringify(document);
-    const html = buildSwaggerHTML(finalPath, document, options);
-    const swaggerInitJS = buildSwaggerInitJS(document, options);
+    const html = buildSwaggerHTML(finalPath, document, customOptions);
+    const swaggerInitJS = buildSwaggerInitJS(document, customOptions);
 
     SwaggerModule.serveDocuments(
       finalPath,

diff --git a/lib/utils/backward-compatilibity-layer.ts b/lib/utils/backward-compatilibity-layer.ts
@@ -0,0 +1,50 @@
+import {
+  FastifySwaggerCustomOptions,
+  SwaggerCustomOptions,
+  SwaggerCustomOptionsLegacy
+} from '../interfaces';
+
+export interface FastifyExtra {
+  initOAuth?: Record<string, any>;
+  staticCSP?: boolean | string | Record<string, string | string[]>;
+  transformStaticCSP?: (header: string) => string;
+  uiHooks?: {
+    onRequest?: Function;
+    preHandler?: Function;
+  };
+}
+
+export interface ProcessSwaggerOptionsOutput {
+  customOptions: SwaggerCustomOptions;
+  extra: FastifyExtra;
+}
+
+export function processSwaggerOptions(
+  options: SwaggerCustomOptionsLegacy = {}
+): ProcessSwaggerOptionsOutput {
+  const unifiedOptions: SwaggerCustomOptions = options;
+  const fastifyOptions: FastifySwaggerCustomOptions = options;
+
+  const customOptions: SwaggerCustomOptions = {
+    useGlobalPrefix: unifiedOptions.useGlobalPrefix,
+    explorer: unifiedOptions.explorer,
+    customCss: unifiedOptions.customCss,
+    customCssUrl: unifiedOptions.customCssUrl,
+    customJs: unifiedOptions.customJs,
+    customfavIcon: unifiedOptions.customfavIcon,
+    swaggerUrl: unifiedOptions.swaggerUrl,
+    customSiteTitle: unifiedOptions.customSiteTitle,
+    validatorUrl: unifiedOptions.validatorUrl,
+    url: unifiedOptions.url,
+    urls: unifiedOptions.urls,
+
+    swaggerOptions: unifiedOptions.swaggerOptions || fastifyOptions.uiConfig
+  };
+
+  const extra = {
+    initOAuth: fastifyOptions.initOAuth,
+    uiHooks: fastifyOptions.uiHooks
+  };
+
+  return { customOptions, extra };
+}