feat: dereference openapi specs to fix broken refs in params

Author: djMax

package.json

@@ -95,7 +95,7 @@
     "dotenv": "^17.2.3",
     "express": "^5.1.0",
     "express-openapi-validator": "^5.6.0",
-    "glob": "^11.0.3",
+    "glob": "^13.0.0",
     "import-in-the-middle": "^2.0.0",
     "minimist": "^1.2.8",
     "moderndash": "^4.0.0",
@@ -118,8 +118,8 @@
     "@types/node": "^24.10.1",
     "@types/request-ip": "^0.0.41",
     "@types/supertest": "^6.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.46.4",
-    "@typescript-eslint/parser": "^8.46.4",
+    "@typescript-eslint/eslint-plugin": "^8.47.0",
+    "@typescript-eslint/parser": "^8.47.0",
     "cpconfig": "^1.4.4",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
@@ -132,7 +132,7 @@
     "tsconfig-paths": "^4.2.0",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.9"
+    "vitest": "^4.0.12"
   },
   "resolutions": {
     "qs": "^6.11.0"

src/openapi.ts

@@ -84,6 +84,21 @@ export async function openApi<
 
     const defaultOptions: OAPIOpts = {
       apiSpec: app.locals.openApiSpecification,
+      // We force full dereferencing of the OpenAPI spec so that all `$ref` schemas are
+      // inlined before express-openapi-validator builds its request coercion rules.
+      // Without this, the coercer sees `schema: { $ref: ... }` for query parameters and
+      // cannot resolve the underlying type, so it falls back to treating the parameter
+      // as a potentially repeated value (i.e., an array). That causes AJV to reject
+      // valid requests with “should be array” errors. Dereferencing ensures the
+      // coercer sees the real primitive type/enum and stops misclassifying params.
+      //
+      // The one downside is that circular references are not supported, so if you
+      // need that, you need to be very careful with enums, and override this option.
+      //
+      // See https://github.com/cdimascio/express-openapi-validator/issues/1119
+      $refParser: {
+        mode: 'dereference',
+      },
       ignoreUndocumented: true,
       validateRequests: {
         allowUnknownQueryParameters: true,