fix(orval): decode escaped JSON Pointer tokens in external $refs (#3380)

Author: wadakatu

packages/orval/src/import-specs.test.ts

@@ -756,6 +756,75 @@ describe('dereferenceExternalRefs', () => {
     expect(result).not.toHaveProperty('x-ext');
   });
 
+  it('should resolve external path-item refs with escaped JSON Pointer tokens (#3380)', () => {
+    // A cross-file path-item `$ref` (e.g. `common.yaml#/paths/~1pets`) is
+    // bundled into an x-ext ref whose pointer keeps the JSON Pointer escape
+    // `~1` (for `/`) and percent-encoding (`%7B`/`%7D` for `{`/`}` in
+    // templated paths). Both must be decoded before walking the external doc.
+    const input = {
+      openapi: '3.0.0',
+      info: { version: '1.0.0', title: 'API' },
+      paths: {
+        '/pets': {
+          $ref: '#/x-ext/abc1234/paths/~1pets',
+        },
+        '/pets/{petId}': {
+          $ref: '#/x-ext/abc1234/paths/~1pets~1%7BpetId%7D',
+        },
+      },
+      'x-ext': {
+        abc1234: {
+          paths: {
+            '/pets': {
+              get: {
+                operationId: 'listPets',
+                responses: { '200': { description: 'ok' } },
+              },
+            },
+            '/pets/{petId}': {
+              get: {
+                operationId: 'getPet',
+                parameters: [
+                  {
+                    name: 'petId',
+                    in: 'path',
+                    required: true,
+                    schema: { type: 'string' },
+                  },
+                ],
+                responses: { '200': { description: 'ok' } },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = dereferenceExternalRef(input) as OpenApiDocument;
+
+    expect(result.paths?.['/pets']).toEqual({
+      get: {
+        operationId: 'listPets',
+        responses: { '200': { description: 'ok' } },
+      },
+    });
+    expect(result.paths?.['/pets/{petId}']).toEqual({
+      get: {
+        operationId: 'getPet',
+        parameters: [
+          {
+            name: 'petId',
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+          },
+        ],
+        responses: { '200': { description: 'ok' } },
+      },
+    });
+    expect(result).not.toHaveProperty('x-ext');
+  });
+
   it('should dereference external doc schemas with internal refs', () => {
     const input = {
       openapi: '3.0.3',

packages/orval/src/import-specs.ts

@@ -344,6 +344,26 @@ function updateInternalRefs(
   return obj;
 }
 
+/**
+ * Decode a single JSON Pointer reference token taken from an x-ext `$ref`.
+ *
+ * The token carries two layers of encoding: it sits in a URI fragment, so it
+ * may be percent-encoded (e.g. `%7B` for `{` in templated paths), and it is a
+ * JSON Pointer token, so `~1`/`~0` stand for `/`/`~` (RFC 6901). Percent-
+ * encoding is the outer layer and is removed first; a malformed sequence is
+ * left as-is rather than throwing. Without this, tokens such as `~1pets`
+ * never match the real `/pets` key and the external `$ref` fails to resolve.
+ */
+function decodeRefToken(token: string): string {
+  let decoded = token;
+  try {
+    decoded = decodeURIComponent(token);
+  } catch {
+    // Malformed percent-encoding — fall back to the raw token.
+  }
+  return decoded.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
 /**
  * Replace x-ext refs with standard component refs, or inline the content.
  * `inliningRefs` tracks the inline chain to break cycles in recursive
@@ -402,7 +422,8 @@ function replaceXExtRefs(
 
           const extDoc = extensions[extKey];
           let refObj: unknown = extDoc;
-          for (const p of parts) {
+          for (const rawPart of parts) {
+            const p = decodeRefToken(rawPart);
             if (
               refObj &&
               (isObject(refObj) || Array.isArray(refObj)) &&

tests/__snapshots__/default/issue-3380-external-path-ref/endpoints.ts

@@ -0,0 +1,26 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 3380 - external path-item $ref
+ * OpenAPI spec version: 1.0.0
+ */
+import axios from 'axios';
+import type { AxiosRequestConfig, AxiosResponse } from 'axios';
+
+export const listPets = (
+  options?: AxiosRequestConfig,
+): Promise<AxiosResponse<string[]>> => {
+  return axios.get(`/pets`, options);
+};
+
+export const getPet = (
+  petId: string,
+  options?: AxiosRequestConfig,
+): Promise<AxiosResponse<string>> => {
+  return axios.get(`/pets/${petId}`, {
+    ...options,
+  });
+};
+
+export type ListPetsResult = AxiosResponse<string[]>;
+export type GetPetResult = AxiosResponse<string>;

tests/api-generation.spec.ts

@@ -233,3 +233,22 @@ test('default issue-1107 emits exports for schemas defined via cross-file $ref',
   expect(pets).toContain("import type { Pet } from './pet';");
   expect(pets).toContain('export type Pets = Pet[];');
 });
+
+test('default issue-3380 resolves external path-item $refs with escaped pointers', async () => {
+  // Regression for #3380: path items defined via a cross-file `$ref`
+  // (`#/paths/~1pets` and `#/paths/~1pets~1%7BpetId%7D`) used to abort
+  // generation with "Can't resolve reference" because the JSON Pointer escape
+  // `~1` and percent-encoding `%7B`/`%7D` were not decoded before resolving
+  // the external document. Both operations must now be generated.
+  // Keep this focused assertion alongside the snapshot so #3380 fails with a
+  // targeted message instead of a full-file snapshot diff.
+  const content = await readFile(
+    generated('default', 'issue-3380-external-path-ref', 'endpoints.ts'),
+    'utf8',
+  );
+
+  expect(content).toContain('export const listPets = (');
+  expect(content).toContain('export const getPet = (');
+  // The templated path ref (`~1pets~1%7BpetId%7D`) decodes to `/pets/{petId}`.
+  expect(content).toContain('`/pets/${petId}`');
+});

tests/configs/default.config.ts

@@ -692,6 +692,16 @@ export default defineConfig({
       target: '../specifications/issue-1107/issue-1107.yaml',
     },
   },
+  'issue-3380-external-path-ref': {
+    output: {
+      target: '../generated/default/issue-3380-external-path-ref/endpoints.ts',
+      clean: true,
+      formatter: 'prettier',
+    },
+    input: {
+      target: '../specifications/issue-3380/issue-3380.yaml',
+    },
+  },
   'boolean-discriminator': {
     output: {
       target: '../generated/default/boolean-discriminator/endpoints.ts',

tests/specifications/issue-3380/issue-3380-common.yaml

@@ -0,0 +1,34 @@
+openapi: 3.0.0
+info:
+  title: Issue 3380 - external paths
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      operationId: listPets
+      responses:
+        '200':
+          description: A list of pet names
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+  /pets/{petId}:
+    get:
+      operationId: getPet
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A pet name
+          content:
+            application/json:
+              schema:
+                type: string
+components: {}

tests/specifications/issue-3380/issue-3380.yaml

@@ -0,0 +1,14 @@
+openapi: 3.0.0
+info:
+  title: Issue 3380 - external path-item $ref
+  version: 1.0.0
+paths:
+  # Regression for #3380: path items defined via a cross-file `$ref`. The
+  # JSON Pointer escape `~1` (for `/`) and percent-encoding (`%7B`/`%7D` for
+  # `{`/`}` in templated paths) in these refs must be decoded for the external
+  # paths to resolve.
+  /pets:
+    $ref: './issue-3380-common.yaml#/paths/~1pets'
+  /pets/{petId}:
+    $ref: './issue-3380-common.yaml#/paths/~1pets~1%7BpetId%7D'
+components: {}