Implement option unsafeRefs

README.md

@@ -331,10 +331,11 @@ new OpenApiValidator(options).install({
         throw { status: 401, message: 'sorry' }
       }
     }
-  }
-  ignorePaths: /.*\/pets$/
+  },
+  ignorePaths: /.*\/pets$/,
   unknownFormats: ['phone-number', 'uuid'],
   multerOpts: { ... },
+  unsafeRefs: false
 });
 ```
 
@@ -461,6 +462,15 @@ Determines whether the validator should coerce value types to match the type def
 - `false` - no type coercion.
 - `"array"` - in addition to coercions between scalar types, coerce scalar data to an array with one element and vice versa (as required by the schema).
 
+### ▪️ unsafeRefs (optional)
+
+As express-openapi-validator uses internally [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser), two choices are possibles :
+
+- `false` **(default)** - It will use the `bundle` method (which prevent circular references issues)
+- `true` - It will use the `dereference` method (which may be needed if you split your specifications into many files and use escaped characters in your [$refs](https://swagger.io/docs/specification/using-ref/))
+
+See this [issue](https://github.com/APIDevTools/json-schema-ref-parser/issues/101#issuecomment-421755168) for more information.
+
 ## The Base URL
 
 The validator will only validate requests, securities, and responses that are under

src/framework/index.ts

@@ -23,7 +23,7 @@ export class OpenAPIFramework {
     visitor: OpenAPIFrameworkVisitor,
   ): Promise<OpenAPIFrameworkInit> {
     const args = this.args;
-    const apiDoc = await this.copy(await this.loadSpec(args.apiDoc));
+    const apiDoc = await this.copy(await this.loadSpec(args.apiDoc, args.unsafeRefs));
     const basePathObs = this.getBasePathsFromServers(apiDoc.servers);
     const basePaths = Array.from(
       basePathObs.reduce((acc, bp) => {
@@ -71,9 +71,9 @@ export class OpenAPIFramework {
     };
   }
 
-  private loadSpec(filePath: string | object): Promise<OpenAPIV3.Document> {
+  private loadSpec(filePath: string | object, unsafeRefs: boolean = false): Promise<OpenAPIV3.Document> {
     // Because of this issue ( https://github.com/APIDevTools/json-schema-ref-parser/issues/101#issuecomment-421755168 )
-    // We need this workaround ( use '$RefParser.dereference' instead of '$RefParser.bundle' )
+    // We need this workaround ( use '$RefParser.dereference' instead of '$RefParser.bundle' ) if asked by user
     if (typeof filePath === 'string') {
       const origCwd = process.cwd();
       const specDir = path.resolve(origCwd, path.dirname(filePath));
@@ -86,7 +86,7 @@ export class OpenAPIFramework {
             fs.readFileSync(absolutePath, 'utf8'),
             { json: true },
           );
-          return $RefParser.dereference(docWithRefs);
+          return (!unsafeRefs) ? $RefParser.bundle(docWithRefs) : $RefParser.dereference(docWithRefs);
         } finally {
           process.chdir(origCwd);
         }
@@ -96,7 +96,7 @@ export class OpenAPIFramework {
         );
       }
     }
-    return $RefParser.dereference(filePath);
+    return (!unsafeRefs) ? $RefParser.bundle(filePath) : $RefParser.dereference(filePath);
   }
 
   private copy<T>(obj: T): T {

src/framework/types.ts

@@ -40,6 +40,7 @@ export interface OpenApiValidatorOpts {
   coerceTypes?: boolean | 'array';
   unknownFormats?: true | string[] | 'ignore';
   multerOpts?: {};
+  unsafeRefs?: boolean
 }
 
 export namespace OpenAPIV3 {
@@ -359,6 +360,7 @@ export interface OpenAPIFrameworkPathObject {
 interface OpenAPIFrameworkArgs {
   apiDoc: OpenAPIV3.Document | string;
   validateApiDoc?: boolean;
+  unsafeRefs?: boolean;
 }
 
 export interface OpenAPIFrameworkAPIContext {

src/index.ts

@@ -27,6 +27,7 @@ export class OpenApiValidator {
     if (options.validateRequests == null) options.validateRequests = true;
     if (options.validateResponses == null) options.validateResponses = false;
     if (options.validateSecurity == null) options.validateSecurity = true;
+    if (options.unsafeRefs == null) options.unsafeRefs = false;
 
     if (options.validateResponses === true) {
       options.validateResponses = {
@@ -62,6 +63,7 @@ export class OpenApiValidator {
   ): Promise<void> | void {
     const p = new OpenApiSpecLoader({
       apiDoc: this.options.apiSpec,
+      unsafeRefs: this.options.unsafeRefs
     })
       .load()
       .then(spec => this.installMiddleware(app, spec));
@@ -234,7 +236,7 @@ export class OpenApiValidator {
   }
 
   private normalizeOptions(options: OpenApiValidatorOpts): void {
-    // Modify the recquest
+    // Modify the request
     if (options.securityHandlers) {
       options.validateSecurity = {
         handlers: options.securityHandlers,