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

.changeset/dynamicref-support.md

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

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

@@ -1015,6 +1015,55 @@ describe(`OpenAPI ${version}`, () => {
       }),
       description: 'anyOf string and binary string',
     },
+    {
+      config: createConfig({
+        input: 'dynamicref-recursive-category-tree.yaml',
+        output: 'dynamicref-recursive-category-tree',
+      }),
+      description: 'resolves $dynamicRef in recursive category tree',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-generic-schema-binding.yaml',
+        output: 'dynamicref-generic-schema-binding',
+      }),
+      description: 'resolves $dynamicRef in generic schema binding',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-nested-workspace-resources.yaml',
+        output: 'dynamicref-nested-workspace-resources',
+      }),
+      description: 'resolves $dynamicRef in nested workspace resources',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-paginated-response.yaml',
+        output: 'dynamicref-paginated-response',
+      }),
+      description: 'resolves $dynamicRef in paginated response template',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-external-ref.yaml',
+        output: 'dynamicref-external-ref',
+      }),
+      description: 'handles external $dynamicRef without crashing',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-non-identifier-key.yaml',
+        output: 'dynamicref-non-identifier-key',
+      }),
+      description: 'handles non-identifier schema keys with $dynamicAnchor',
+    },
+    {
+      config: createConfig({
+        input: 'dynamicref-scope-isolation.yaml',
+        output: 'dynamicref-scope-isolation',
+      }),
+      description: 'keeps $dynamicRef bindings isolated between sibling schemas',
+    },
   ];
 
   it.each(scenarios)('$description', async ({ config }) => {

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-generic-schema-binding/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { ClientOptions, Group, ListGroupsData, ListGroupsErrors, ListGroupsResponse, ListGroupsResponses, ListUsersData, ListUsersErrors, ListUsersResponse, ListUsersResponses, PaginatedGroupResponse, PaginatedTemplate, PaginatedUserResponse, User } from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-generic-schema-binding/types.gen.ts

@@ -0,0 +1,82 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+    baseUrl: 'https://api.dynamicref.test' | (string & {});
+};
+
+export type User = {
+    id: string;
+    email: string;
+};
+
+export type Group = {
+    id: string;
+    name: string;
+};
+
+export type PaginatedTemplate = {
+    items: Array<unknown>;
+    total: number;
+    page: number;
+    pageSize: number;
+};
+
+export type PaginatedUserResponse = {
+    items: Array<User>;
+    total: number;
+    page: number;
+    pageSize: number;
+};
+
+export type PaginatedGroupResponse = {
+    items: Array<Group>;
+    total: number;
+    page: number;
+    pageSize: number;
+};
+
+export type ListUsersData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/users';
+};
+
+export type ListUsersErrors = {
+    /**
+     * Error response
+     */
+    default: unknown;
+};
+
+export type ListUsersResponses = {
+    /**
+     * User page
+     */
+    200: PaginatedUserResponse;
+};
+
+export type ListUsersResponse = ListUsersResponses[keyof ListUsersResponses];
+
+export type ListGroupsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/groups';
+};
+
+export type ListGroupsErrors = {
+    /**
+     * Error response
+     */
+    default: unknown;
+};
+
+export type ListGroupsResponses = {
+    /**
+     * Group page
+     */
+    200: PaginatedGroupResponse;
+};
+
+export type ListGroupsResponse = ListGroupsResponses[keyof ListGroupsResponses];

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-nested-workspace-resources/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { BaseFolder, BaseResource, ClientOptions, Document, GetWorkspaceData, GetWorkspaceErrors, GetWorkspaceResponse, GetWorkspaceResponses, WorkspaceFolder, WorkspaceResource, WorkspaceResponse } from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-nested-workspace-resources/types.gen.ts

@@ -0,0 +1,61 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+    baseUrl: 'https://api.dynamicref.test' | (string & {});
+};
+
+export type Document = {
+    kind: 'document';
+    id: string;
+    title: string;
+};
+
+export type BaseFolder = {
+    kind: 'folder';
+    id: string;
+    name: string;
+    children: Array<Document | BaseFolder>;
+    shortcuts: Array<unknown>;
+};
+
+export type BaseResource = Document | unknown;
+
+export type WorkspaceFolder = {
+    kind: 'folder';
+    id: string;
+    name: string;
+    children: Array<Document | WorkspaceFolder>;
+    shortcuts: Array<unknown>;
+} & {
+    permissions: Array<'read' | 'write' | 'admin'>;
+};
+
+export type WorkspaceResource = Document | WorkspaceFolder;
+
+export type WorkspaceResponse = {
+    root: WorkspaceFolder;
+    related: Array<WorkspaceResource>;
+};
+
+export type GetWorkspaceData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/workspaces/current';
+};
+
+export type GetWorkspaceErrors = {
+    /**
+     * Error response
+     */
+    default: unknown;
+};
+
+export type GetWorkspaceResponses = {
+    /**
+     * Workspace with nested folders and linked resources
+     */
+    200: WorkspaceResponse;
+};
+
+export type GetWorkspaceResponse = GetWorkspaceResponses[keyof GetWorkspaceResponses];

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-non-identifier-key/index.ts

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

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-non-identifier-key/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 BaseCategory = {
+    id: string;
+    children: Array<BaseCategory>;
+};
+
+export type GetTreeData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/tree';
+};
+
+export type GetTreeErrors = {
+    /**
+     * Error response
+     */
+    default: unknown;
+};
+
+export type GetTreeResponses = {
+    /**
+     * Tree node
+     */
+    200: BaseCategory;
+};
+
+export type GetTreeResponse = GetTreeResponses[keyof GetTreeResponses];

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-paginated-response/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { ClientOptions, Group, ListGroupsData, ListGroupsErrors, ListGroupsResponse, ListGroupsResponses, ListUsersData, ListUsersErrors, ListUsersResponse, ListUsersResponses, PaginatedTemplate, User } from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-paginated-response/types.gen.ts

@@ -0,0 +1,78 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+    baseUrl: 'https://api.dynamicref.test' | (string & {});
+};
+
+export type User = {
+    id: string;
+    email: string;
+};
+
+export type Group = {
+    id: string;
+    name: string;
+};
+
+export type PaginatedTemplate = {
+    items: Array<unknown>;
+    total: number;
+    page: number;
+    pageSize: number;
+};
+
+export type ListUsersData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/users';
+};
+
+export type ListUsersErrors = {
+    /**
+     * Error response
+     */
+    default: unknown;
+};
+
+export type ListUsersResponses = {
+    /**
+     * User page
+     */
+    200: {
+        items: Array<User>;
+        total: number;
+        page: number;
+        pageSize: number;
+    };
+};
+
+export type ListUsersResponse = ListUsersResponses[keyof ListUsersResponses];
+
+export type ListGroupsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/groups';
+};
+
+export type ListGroupsErrors = {
+    /**
+     * Error response
+     */
+    default: unknown;
+};
+
+export type ListGroupsResponses = {
+    /**
+     * Group page
+     */
+    200: {
+        items: Array<Group>;
+        total: number;
+        page: number;
+        pageSize: number;
+    };
+};
+
+export type ListGroupsResponse = ListGroupsResponses[keyof ListGroupsResponses];

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-recursive-category-tree/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { BaseCategory, ClientOptions, GetCategoryTreeData, GetCategoryTreeErrors, GetCategoryTreeResponse, GetCategoryTreeResponses, LocalizedCategory } from './types.gen';