feat: add $dynamicRef / $dynamicAnchor schema resolution for OpenAPI 3.1

.changeset/dynamicref-support.md

@@ -0,0 +1,6 @@
+---
+"@hey-api/shared": minor
+"@hey-api/spec-types": minor
+---
+
+add `$dynamicRef` / `$dynamicAnchor` schema resolution for OpenAPI 3.1

packages/openapi-ts-tests/main/test/3.1.x.test.ts

@@ -1015,6 +1015,49 @@ describe(`OpenAPI ${version}`, () => {
       }),
       description: 'anyOf string and binary string',
     },
+    {
+      config: createConfig({
+        input: 'dynamicref-petstore-showcase.yaml',
+        output: 'dynamicref-petstore-showcase',
+      }),
+      description: 'resolves $dynamicRef in petstore showcase',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-external-ref.yaml',
+        output: 'dynamicref-external-ref',
+      }),
+      description: 'handles external $dynamicRef without crashing',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-scope-isolation.yaml',
+        output: 'dynamicref-scope-isolation',
+      }),
+      description: 'keeps $dynamicRef bindings isolated between sibling schemas',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-circular-oneof.yaml',
+        output: 'dynamicref-circular-oneof',
+      }),
+      description:
+        'detects circular $dynamicRef through oneOf (emits type alias — TS2456, unfixable)',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-circular-allof.yaml',
+        output: 'dynamicref-circular-allof',
+      }),
+      description: 'emits interface extends for circular $dynamicRef through allOf',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-circular-naked.yaml',
+        output: 'dynamicref-circular-naked',
+      }),
+      description: 'emits interface extends for circular $dynamicRef without allOf',
+    },
   ];
 
   it.each(scenarios)('$description', async ({ config }) => {

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-circular-allof/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { Branch, ClientOptions, GetBranchesData, GetBranchesResponse, GetBranchesResponses, Leaf, NodeTemplate } from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-circular-allof/types.gen.ts

@@ -0,0 +1,36 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+    baseUrl: 'https://api.example.com' | (string & {});
+};
+
+export type NodeTemplate<nodeType> = {
+    id: string;
+    child?: nodeType;
+};
+
+export interface Branch extends NodeTemplate<Branch> {
+    name: string;
+    level?: number;
+}
+
+export type Leaf = {
+    id: string;
+    value?: string;
+};
+
+export type GetBranchesData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/branches';
+};
+
+export type GetBranchesResponses = {
+    /**
+     * Branch list
+     */
+    200: Array<Branch>;
+};
+
+export type GetBranchesResponse = GetBranchesResponses[keyof GetBranchesResponses];

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-circular-naked/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { ClientOptions, GetNodesData, GetNodesResponse, GetNodesResponses, Node, NodeTemplate } from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-circular-naked/types.gen.ts

@@ -0,0 +1,29 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+    baseUrl: 'https://api.example.com' | (string & {});
+};
+
+export type NodeTemplate<nodeType> = {
+    id: string;
+    child?: nodeType;
+};
+
+export interface Node extends NodeTemplate<Node> {
+}
+
+export type GetNodesData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/nodes';
+};
+
+export type GetNodesResponses = {
+    /**
+     * Node list
+     */
+    200: Array<Node>;
+};
+
+export type GetNodesResponse = GetNodesResponses[keyof GetNodesResponses];

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-circular-oneof/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { ClientOptions, GetTreeData, GetTreeResponse, GetTreeResponses, TreeNode, TreeNodeLeaf, TreeNodeTemplate } from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-circular-oneof/types.gen.ts

@@ -0,0 +1,34 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+    baseUrl: 'https://api.example.com' | (string & {});
+};
+
+export type TreeNodeTemplate<nodeType> = {
+    id: string;
+    label: string;
+    child?: nodeType;
+};
+
+export type TreeNode = TreeNodeLeaf | TreeNodeTemplate<TreeNode>;
+
+export type TreeNodeLeaf = {
+    id: string;
+    label: string;
+};
+
+export type GetTreeData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/tree';
+};
+
+export type GetTreeResponses = {
+    /**
+     * Tree nodes
+     */
+    200: Array<TreeNode>;
+};
+
+export type GetTreeResponse = GetTreeResponses[keyof GetTreeResponses];

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-external-ref/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { ClientOptions, Container, GetContainersData, GetContainersErrors, GetContainersResponse, GetContainersResponses } from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-external-ref/types.gen.ts

@@ -0,0 +1,33 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+    baseUrl: 'https://api.dynamicref.test' | (string & {});
+};
+
+export type Container = {
+    id: string;
+    item: unknown;
+};
+
+export type GetContainersData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/containers';
+};
+
+export type GetContainersErrors = {
+    /**
+     * Error response
+     */
+    default: unknown;
+};
+
+export type GetContainersResponses = {
+    /**
+     * Container list
+     */
+    200: Array<Container>;
+};
+
+export type GetContainersResponse = GetContainersResponses[keyof GetContainersResponses];

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-petstore-showcase/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { ApiEnvelopeTemplate, BaseSpeciesCategory, ClientOptions, CreatePetData, CreatePetErrors, CreatePetResponse, CreatePetResponses, Document, GetPetData, GetPetErrors, GetPetResponse, GetPetResponses, GetShelterResourcesData, GetShelterResourcesErrors, GetShelterResourcesResponse, GetShelterResourcesResponses, GetSpeciesTreeData, GetSpeciesTreeErrors, GetSpeciesTreeResponse, GetSpeciesTreeResponses, Link, ListOwnersData, ListOwnersErrors, ListOwnersResponse, ListOwnersResponses, ListPetsData, ListPetsErrors, ListPetsResponse, ListPetsResponses, LocalizedSpeciesCategory, Owner, PaginatedOwnerItems, PaginatedPetItems, PaginatedTemplate, Pet, PetCreateRequest, PetFields, ShelterFolder, ShelterFolderTemplate, ShelterResource } from './types.gen';