fix(core): inline header schema when $ref points outside #/components/parameters (#3408)

A header parameter referenced via a JSON Pointer $ref that targets
another path's parameter (e.g. `#/paths/~1requestA/post/parameters/0`)
used to be typed as `N0` and imported from a non-existent `./n0`
module. The synthesized name comes from sanitizing the trailing `0`
segment, but `generateParameterDefinition` only emits `export type`s
for slots under `#/components/parameters/*`, so the import dangled.

Gate the imports surfaced by `getParameters` on `isComponentRef(p.$ref)`
so non-component refs drop the dangling import and `getQueryParams`
inlines the resolved parameter's schema via its existing fallback.
Mirrors the parameter-side fix to the same class of bug that #398
addressed for schema refs in `resolvers/value.ts`.

Fixes #1879

Author: wadakatu

packages/core/src/getters/parameters.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+
+import { createTestContextSpec } from '../test-utils/context';
+import type { OpenApiParameterObject, OpenApiReferenceObject } from '../types';
+import { getParameters } from './parameters';
+
+describe('getParameters', () => {
+  it('resolves a header parameter referenced via #/components/parameters/* and surfaces its named import', () => {
+    // Refs that target a slot under `#/components/<NAMED_COMPONENT_SECTIONS>`
+    // have a matching `export type` emitted by `generateParameterDefinition`,
+    // so the import must flow through to downstream getters (e.g.
+    // `getQueryParams` renders the header type as that named import).
+    const sharedHeader: OpenApiParameterObject = {
+      name: 'Content-Type',
+      in: 'header',
+      schema: { type: 'string' },
+    };
+    const context = createTestContextSpec({
+      spec: {
+        components: { parameters: { ContentTypeHeader: sharedHeader } },
+      },
+    });
+
+    const ref: OpenApiReferenceObject = {
+      $ref: '#/components/parameters/ContentTypeHeader',
+    };
+
+    const result = getParameters({ parameters: [ref], context });
+
+    expect(result.header).toHaveLength(1);
+    expect(result.header[0].parameter.name).toBe('Content-Type');
+    expect(result.header[0].imports).toEqual([
+      { name: 'ContentTypeHeader', schemaName: 'ContentTypeHeader' },
+    ]);
+  });
+
+  it('drops imports when a header parameter $ref targets a non-component slot (issue #1879)', () => {
+    // Repro for #1879: JSON Pointer refs into another path's `parameters` array
+    // (`#/paths/~1requestA/post/parameters/0`) resolve to a synthesized name
+    // like `N0` that has no corresponding `export type`. Surfacing that import
+    // would produce a dangling reference downstream — drop it so consumers
+    // inline the resolved parameter's `schema` instead. Mirrors the #398 fix
+    // applied to schema refs in `resolvers/value.ts`.
+    const requestAHeader: OpenApiParameterObject = {
+      name: 'Content-Type',
+      in: 'header',
+      schema: { type: 'string' },
+    };
+    const context = createTestContextSpec({
+      spec: {
+        paths: {
+          '/requestA': {
+            post: { parameters: [requestAHeader], responses: {} },
+          },
+        },
+      },
+    });
+
+    const ref: OpenApiReferenceObject = {
+      $ref: '#/paths/~1requestA/post/parameters/0',
+    };
+
+    const result = getParameters({ parameters: [ref], context });
+
+    expect(result.header).toHaveLength(1);
+    expect(result.header[0].parameter.name).toBe('Content-Type');
+    // The resolver synthesizes `{ name: 'N0', schemaName: '0' }` from the
+    // numeric path segment. Without the fix this leaks downstream and types
+    // the header as `N0` while importing it from `./n0`.
+    expect(result.header[0].imports).toEqual([]);
+  });
+});

packages/core/src/getters/parameters.ts

@@ -6,6 +6,7 @@ import type {
   OpenApiReferenceObject,
 } from '../types';
 import { isReference } from '../utils';
+import { isComponentRef } from './ref';
 
 interface GetParametersOptions {
   parameters: (OpenApiReferenceObject | OpenApiParameterObject)[];
@@ -28,7 +29,13 @@ export function getParameters({
         location === 'query' ||
         location === 'header'
       ) {
-        result[location].push({ parameter, imports });
+        // Refs that don't target a named component slot (e.g. bundler-emitted
+        // `#/paths/.../parameters/0`) have no corresponding `export type` from
+        // `generateParameterDefinition`, so emitting a named import would
+        // dangle. Inline the resolved parameter's schema instead. Mirrors the
+        // #398 fix in `resolvers/value.ts`. See issue #1879.
+        const safeImports = p.$ref && isComponentRef(p.$ref) ? imports : [];
+        result[location].push({ parameter, imports: safeImports });
       }
     } else {
       if (p.in === 'query' || p.in === 'path' || p.in === 'header') {

packages/core/src/getters/query-params.test.ts

@@ -500,4 +500,60 @@ describe('getQueryParams getter', () => {
       expect(result?.nonPrimitiveKeys).toBeUndefined();
     });
   });
+
+  // Locks the contract that getParameters/issue-1879 fix relies on: when the
+  // caller surfaces an import (i.e. the parameter resolved to a named
+  // `#/components/parameters/*` slot), the type must be that import name, and
+  // when it does not, the parameter's `schema` must be inlined as `string`.
+  describe('parameter import handling', () => {
+    it('renders the import name when a non-empty import is supplied', () => {
+      const result = getQueryParams({
+        queryParams: [
+          {
+            parameter: {
+              name: 'Content-Type',
+              in: 'header',
+              schema: { type: 'string' },
+            },
+            imports: [
+              { name: 'ContentTypeHeader', schemaName: 'ContentTypeHeader' },
+            ],
+          },
+        ],
+        operationName: '',
+        context,
+        suffix: 'headers',
+      });
+
+      expect(result?.schema.model.trim()).toBe(
+        `export type Headers = {\n'Content-Type'?: ContentTypeHeader;\n};`,
+      );
+    });
+
+    it('inlines the resolved schema as `string` when no import is surfaced (issue #1879)', () => {
+      // Mirrors what getParameters now feeds in for header refs like
+      // `#/paths/~1requestA/post/parameters/0`: the resolved parameter object
+      // with empty imports. Without the upstream fix the resolver would have
+      // emitted `{ name: 'N0', ... }` here, producing a dangling `N0` type.
+      const result = getQueryParams({
+        queryParams: [
+          {
+            parameter: {
+              name: 'Content-Type',
+              in: 'header',
+              schema: { type: 'string' },
+            },
+            imports: [],
+          },
+        ],
+        operationName: '',
+        context,
+        suffix: 'headers',
+      });
+
+      expect(result?.schema.model.trim()).toBe(
+        `export type Headers = {\n'Content-Type'?: string;\n};`,
+      );
+    });
+  });
 });

tests/__snapshots__/fetch/issue-1879/endpoints.ts

@@ -0,0 +1,90 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1879 - Header $ref to another path's parameter
+ * OpenAPI spec version: 1.0.0
+ */
+import type {
+  RequestABody,
+  RequestAHeaders,
+  RequestBBody,
+  RequestBHeaders,
+} from './model';
+
+export type requestAResponse200 = {
+  data: void;
+  status: 200;
+};
+
+export type requestAResponseSuccess = requestAResponse200 & {
+  headers: Headers;
+};
+export type requestAResponse = requestAResponseSuccess;
+
+export const getRequestAUrl = () => {
+  return `/requestA`;
+};
+
+/**
+ * @summary Request A
+ */
+export const requestA = async (
+  requestABody?: RequestABody,
+  headers?: RequestAHeaders,
+  options?: RequestInit,
+): Promise<requestAResponse> => {
+  const res = await fetch(getRequestAUrl(), {
+    ...options,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+      ...options?.headers,
+    },
+    body: JSON.stringify(requestABody),
+  });
+
+  const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+
+  const data: requestAResponse['data'] = body ? JSON.parse(body) : undefined;
+  return { data, status: res.status, headers: res.headers } as requestAResponse;
+};
+
+export type requestBResponse200 = {
+  data: void;
+  status: 200;
+};
+
+export type requestBResponseSuccess = requestBResponse200 & {
+  headers: Headers;
+};
+export type requestBResponse = requestBResponseSuccess;
+
+export const getRequestBUrl = () => {
+  return `/requestB`;
+};
+
+/**
+ * @summary Request B
+ */
+export const requestB = async (
+  requestBBody?: RequestBBody,
+  headers?: RequestBHeaders,
+  options?: RequestInit,
+): Promise<requestBResponse> => {
+  const res = await fetch(getRequestBUrl(), {
+    ...options,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+      ...options?.headers,
+    },
+    body: JSON.stringify(requestBBody),
+  });
+
+  const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+
+  const data: requestBResponse['data'] = body ? JSON.parse(body) : undefined;
+  return { data, status: res.status, headers: res.headers } as requestBResponse;
+};

tests/__snapshots__/fetch/issue-1879/model/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1879 - Header $ref to another path's parameter
+ * OpenAPI spec version: 1.0.0
+ */
+
+export * from './requestABody';
+export * from './requestAHeaders';
+export * from './requestBBody';
+export * from './requestBHeaders';

tests/__snapshots__/fetch/issue-1879/model/requestABody.ts

@@ -0,0 +1,10 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1879 - Header $ref to another path's parameter
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type RequestABody = {
+  message?: string;
+};

tests/__snapshots__/fetch/issue-1879/model/requestAHeaders.ts

@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1879 - Header $ref to another path's parameter
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type RequestAHeaders = {
+  /**
+   * The expected content type.
+   * @pattern ^application\/json$
+   */
+  'Content-Type'?: string;
+};

tests/__snapshots__/fetch/issue-1879/model/requestBBody.ts

@@ -0,0 +1,10 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1879 - Header $ref to another path's parameter
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type RequestBBody = {
+  status?: string;
+};

tests/__snapshots__/fetch/issue-1879/model/requestBHeaders.ts

@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1879 - Header $ref to another path's parameter
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type RequestBHeaders = {
+  /**
+   * The expected content type.
+   * @pattern ^application\/json$
+   */
+  'Content-Type'?: string;
+};

tests/api-generation.spec.ts

@@ -329,3 +329,33 @@ test('react-query issue-1522 passes the enabled option into the queryOptions mut
   const occurrences = content.split(expectedMutatorCall).length - 1;
   expect(occurrences).toBe(2);
 });
+
+test('fetch issue-1879 inlines header schema when $ref targets another path parameter', async () => {
+  // Regression for #1879: a header parameter referenced via a JSON Pointer
+  // `$ref` to another path's parameter
+  // (`#/paths/~1requestA/post/parameters/0`) used to be typed as `N0` (the
+  // sanitized last segment of the ref) and imported from a non-existent
+  // `./n0` module, because the resolver's synthesized name leaked downstream
+  // even though `generateParameterDefinition` only emits types for slots
+  // under `#/components/parameters/*`. The fix gates that import on
+  // `isComponentRef` so non-component refs inline the resolved parameter's
+  // schema (`string`) instead. Keep this focused assertion alongside the
+  // snapshot so #1879 fails with a targeted message rather than a full-file
+  // snapshot diff.
+  const headersContent = await readFile(
+    generated('fetch', 'issue-1879', 'model', 'requestBHeaders.ts'),
+    'utf8',
+  );
+
+  // The header type must be inlined as `string` with no dangling reference.
+  expect(headersContent).toContain("'Content-Type'?: string;");
+  expect(headersContent).not.toMatch(/\bN0\b/);
+  expect(headersContent).not.toContain('./n0');
+
+  // And no synthesized `n0` module should be emitted alongside it.
+  const indexContent = await readFile(
+    generated('fetch', 'issue-1879', 'model', 'index.ts'),
+    'utf8',
+  );
+  expect(indexContent).not.toMatch(/\bn0\b/);
+});