feat: add support custom type imports with --override-import-type

.changeset/gentle-sites-pump.md

@@ -0,0 +1,8 @@
+---
+'@openapi-qraft/tanstack-query-react-plugin': minor
+---
+
+New `--override-import-type` option for the CLI that has been implemented to allow overriding import paths for specific
+types in generated files
+
+This feature has been designed to enable using custom type implementations instead of the default ones

.changeset/global-redocly-config.md

@@ -0,0 +1,8 @@
+---
+'@openapi-qraft/cli': minor
+---
+
+Global x-openapi-qraft configuration has been added to the Redocly config support.
+
+This feature has been implemented to allow specifying x-openapi-qraft options at the global level in the Redocly
+configuration, rather than repeating the same options for each API client.

.changeset/orange-foxes-shave.md

@@ -0,0 +1,7 @@
+---
+'@openapi-qraft/tanstack-query-react-plugin': minor
+'@openapi-qraft/react': minor
+---
+
+Updated the generated services to always import types from `@tanstack/react-query` instead of `@tanstack/query-core`.
+This simplifies the generated code and makes it easier to override types if needed.

.github/actions/spelling/allow.txt

@@ -3,3 +3,4 @@ https
 ssh
 ubuntu
 workarounds
+createapiclient

packages/cli/README.md

@@ -24,43 +24,55 @@ Usage: openapi-qraft --plugin tanstack-query-react --plugin openapi-typescript [
 Generate a type-safe TanStack Query client for React from an OpenAPI Document.
 
 Arguments:
-  input                                            Input OpenAPI Document file path, URL (json, yml) (default: null)
+  input                                               Input OpenAPI Document file path, URL (json, yml) (default: null)
 
 Options:
-  -o, --output-dir <path>                          Output directory for generated services
-  -rm, --clean                                     Clean output directory before generating services
-  --filter-services <glob-patterns...>             Filter services to be generated using glob patterns. Example: "/user/**,/post/**". For more details, see the NPM `micromatch` package documentation.
-  --operation-predefined-parameters <patterns...>  Predefined parameters for services. The specified service parameters will be optional. Example: "/**:header.x-monite-version,query.x-api-key" or "get /**:header.x-monite-entity-id"
-  --operation-name-modifier <patterns...>          Modifies operation names using a pattern. Use the `==>` operator to separate the regular expression (left) and the substitution string (right). For example: "post /**:[A-Za-z]+Id ==> createOne"
-  --postfix-services <string>                      Postfix to be added to the generated service name (eg: Service)
-  --service-name-base <endpoint[<index>] | tags>   Use OpenAPI Operation `endpoint[<index>]` path part (e.g.: "/0/1/2") or `tags` as the base name of the service. (default: "endpoint[0]")
-  --file-header <string>                           Header to be added to the generated file (eg: /* eslint-disable */)
-  --redocly [config]                               Use the Redocly configuration to generate multiple API clients
-                                                   If the [config] parameter is not specified, the default Redocly configuration will be used: [redocly.yaml | redocly.yml | .redocly.yaml | .redocly.yml].
-                                                   For more information about this option, use the command: --redocly-help
-                                                   Examples: "openapi-qraft --redocly", "openapi-qraft my-api@v1 external-api --redocly", "openapi-qraft --redocly
-                                                   ./my-redocly-config.yaml"
-  --openapi-types-import-path <path>               Path to schema types file (.d.ts), e.g.: "../schema.d.ts"
-  --explicit-import-extensions [extension]         All import statements will contain an explicit file extension. Ideal for projects using ECMAScript modules. (choices: ".js", ".ts", preset: ".js")
-  --export-openapi-types [bool]                    Add an export statement of the generated OpenAPI document types from the `./index.ts' file. Useful for sharing types within your project. (default: true)
-  --queryable-write-operations [bool]              Enable generation of query hooks (useQuery, useSuspenseQuery, etc.) for writable HTTP methods like POST, PUT, PATCH. By default, only mutation hooks are generated for writable operations.
-  --openapi-types-file-name <path>                 OpenAPI Schema types file name, e.g.: "schema.d.ts" (default: "schema.ts")
-  --enum                                           Export true TS enums instead of unions
-  --enum-values                                    Export enum values as arrays.
-  --dedupe-enums                                   Dedupe enum types when `--enum` is set
-  -t, --export-type                                Export top-level `type` instead of `interface`
-  --immutable                                      Generate readonly types
-  --additional-properties                          Treat schema objects as if `additionalProperties: true` is set
-  --empty-objects-unknown                          Generate `unknown` instead of `Record<string, never>` for empty objects
-  --default-non-nullable                           Set to `false` to ignore default values when generating non-nullable types
-  --properties-required-by-default                 Treat schema objects as if `required` is set to all properties by default
-  --array-length                                   Generate tuples using array minItems / maxItems
-  --path-params-as-types                           Convert paths to template literal types
-  --alphabetize                                    Sort object keys alphabetically
-  --exclude-deprecated                             Exclude deprecated types
-  --no-blob-from-binary                            If this option is enabled, binary format fields will not be converted to Blob types, preserving the native representation
-  --explicit-component-exports                     Enabling this option will export API components as separate type aliases, alongside `components` interface
-  -h, --help                                       display help for command
+  -o, --output-dir <path>                             Output directory for generated services
+  -rm, --clean                                        Clean output directory before generating services
+  --filter-services <glob-patterns...>                Filter services to be generated using glob patterns. Example: "/user/**,/post/**". For more details, see the NPM `micromatch` package documentation.
+  --operation-predefined-parameters <patterns...>     Predefined parameters for services. The specified service parameters will be optional. Example: "/**:header.x-monite-version,query.x-api-key" or
+                                                      "get /**:header.x-monite-entity-id"
+  --operation-name-modifier <patterns...>             Modifies operation names using a pattern. Use the `==>` operator to separate the regular expression (left) and the substitution string (right). For
+                                                      example: "post /**:[A-Za-z]+Id ==> createOne"
+  --postfix-services <string>                         Postfix to be added to the generated service name (eg: Service)
+  --service-name-base <endpoint[<index>] | tags>      Use OpenAPI Operation `endpoint[<index>]` path part (e.g.: "/0/1/2") or `tags` as the base name of the service. (default: "endpoint[0]")
+  --file-header <string>                              Header to be added to the generated file (eg: /* eslint-disable */)
+  --redocly [config]                                  Use the Redocly configuration to generate multiple API clients
+                                                      If the [config] parameter is not specified, the default Redocly configuration will be used: [redocly.yaml | redocly.yml | .redocly.yaml |
+                                                      .redocly.yml].
+                                                      For more information about this option, use the command: --redocly-help
+                                                      Examples:
+                                                      $ bin --redocly
+                                                      $ bin my-api --redocly
+                                                      $ bin my-api@v1 my-api@v2 --redocly
+                                                      $ bin --redocly ./my-redocly-config.yaml
+  --openapi-types-import-path <path>                  Path to schema types file (.d.ts), e.g.: "../schema.d.ts"
+  --explicit-import-extensions [extension]            All import statements will contain an explicit file extension. Ideal for projects using ECMAScript modules. (choices: ".js", ".ts", preset: ".js")
+  --export-openapi-types [bool]                       Add an export statement of the generated OpenAPI document types from the `./index.ts' file. Useful for sharing types within your project. Default:
+                                                      true when --plugin openapi-typescript is used. (default: true)
+  --queryable-write-operations [bool]                 Enable generation of query hooks (useQuery, useSuspenseQuery, etc.) for writable HTTP methods like POST, PUT, PATCH. By default, only mutation hooks
+                                                      are generated for writable operations.
+  --create-api-client-fn <functionName> [options...]  Configure API client creation function. Allows specifying the function name, included services, and callbacks. Can be specified multiple times to
+                                                      generate several different API client functions from a single OpenAPI document. (default: null)
+  --override-import-type <pathname overrides...>      Override import paths for specific types in generated files. This allows using custom type implementations instead of the default ones. Expected
+                                                      format: filepath originalModule:importTypeName:customImportPath
+  --openapi-types-file-name <path>                    OpenAPI Schema types file name, e.g.: "schema.d.ts" (default: "schema.ts")
+  --enum                                              Export true TS enums instead of unions
+  --enum-values                                       Export enum values as arrays.
+  --dedupe-enums                                      Dedupe enum types when `--enum` is set
+  -t, --export-type                                   Export top-level `type` instead of `interface`
+  --immutable                                         Generate readonly types
+  --additional-properties                             Treat schema objects as if `additionalProperties: true` is set
+  --empty-objects-unknown                             Generate `unknown` instead of `Record<string, never>` for empty objects
+  --default-non-nullable                              Set to `false` to ignore default values when generating non-nullable types
+  --properties-required-by-default                    Treat schema objects as if `required` is set to all properties by default
+  --array-length                                      Generate tuples using array minItems / maxItems
+  --path-params-as-types                              Convert paths to template literal types
+  --alphabetize                                       Sort object keys alphabetically
+  --exclude-deprecated                                Exclude deprecated types
+  --no-blob-from-binary                               If this option is enabled, binary format fields will not be converted to Blob types, preserving the native representation
+  --explicit-component-exports                        Enabling this option will export API components as separate type aliases, alongside `components` interface
+  -h, --help                                          display help for command
 ```
 
 ## Usage example

packages/plugin/src/lib/RedoclyConfigCommand.ts

@@ -104,8 +104,16 @@ export class RedoclyConfigCommand extends Command {
         }
 
         redocAPIsToQraftEntries.forEach(([apiName, api]) => {
+          const globalQraftConfig =
+            'x-openapi-qraft' in redoc.rawConfig
+              ? redoc.rawConfig['x-openapi-qraft']
+              : undefined;
+
           const {
-            ['x-openapi-qraft']: { ['output-dir']: outputDir, ...qraftConfig },
+            ['x-openapi-qraft']: {
+              ['output-dir']: outputDir,
+              ...apiQraftConfig
+            },
           } = api;
 
           const cwd = fileURLToPath(this.cwd);
@@ -115,7 +123,10 @@ export class RedoclyConfigCommand extends Command {
             ...parseConfigToArgs({
               redocly: relative(cwd, redocConfigFile),
               'output-dir': relative(cwd, outputDir),
-              ...qraftConfig,
+              ...(globalQraftConfig && typeof globalQraftConfig === 'object'
+                ? globalQraftConfig
+                : undefined),
+              ...apiQraftConfig,
             }),
           ];
         });
@@ -155,7 +166,7 @@ export class RedoclyConfigCommand extends Command {
           spinner.info(
             `Generating API client for ${c.magenta(apiName)} with the following parameters:\n` +
               c.gray.italic('bin ') +
-              `${c.green.italic(openAPIDocument)}` +
+              `${c.green.italic(openAPIDocument)} ` +
               apiProcessArgv
                 .map((arg) =>
                   arg.startsWith('--')

packages/plugin/src/lib/parseConfigToArgs.spec.ts

@@ -130,4 +130,36 @@ describe('configParser', () => {
       'callbacks:setQueryData,getQueryData,fetchQuery',
     ]);
   });
+
+  it('should parse complex nested mappings', () => {
+    expect(
+      parseConfigToArgs({
+        'override-import-type': {
+          services: {
+            '@openapi-qraft/tanstack-query-react-types': {
+              ResultError: '../ResponseError',
+              ResultSuccess: '../ResultSuccess',
+            },
+            '@openapi-qraft/react': {
+              UseQueryOperation: '../UseQueryOperation',
+            },
+          },
+          'create-client': {
+            '@openapi-qraft/react': {
+              UseQueryOperation: '../UseQueryOperation',
+            },
+          },
+        },
+      })
+    ).toEqual([
+      '--override-import-type',
+      'services',
+      '@openapi-qraft/tanstack-query-react-types:ResultError:../ResponseError',
+      '@openapi-qraft/tanstack-query-react-types:ResultSuccess:../ResultSuccess',
+      '@openapi-qraft/react:UseQueryOperation:../UseQueryOperation',
+      '--override-import-type',
+      'create-client',
+      '@openapi-qraft/react:UseQueryOperation:../UseQueryOperation',
+    ]);
+  });
 });

packages/react-client/redocly.yaml

@@ -1,3 +1,8 @@
+x-openapi-qraft:
+  plugin:
+    tanstack-query-react: true
+    openapi-typescript: true
+
 rules:
   operation-operationId-unique:
     severity: 'error'
@@ -6,9 +11,6 @@ apis:
   main:
     root: ../test-fixtures/openapi.json
     x-openapi-qraft:
-      plugin:
-        tanstack-query-react: true
-        openapi-typescript: true
       output-dir: src/tests/fixtures/api
       clean: true
       enum-values: true
@@ -37,12 +39,27 @@ apis:
       filter-services:
         - '/approval_policies/**'
         - '/files/**'
+      operation-predefined-parameters:
+        '/approval_policies/**': 'header.x-monite-entity-id'
+      override-import-type:
+        services:
+          '@openapi-qraft/tanstack-query-react-types':
+            OperationError: '../../type-overrides/operation-error.js'
+          '@tanstack/react-query':
+            UseSuspenseQueryOptions: '../../type-overrides/suspense-query.js'
+            UseSuspenseQueryResult: '../../type-overrides/suspense-query.js'
+            UseInfiniteQueryResult: '../../type-overrides/use-infinite-query-result.js'
+        create-api-client:
+          '@openapi-qraft/react':
+            CreateAPIQueryClientOptions: '../type-overrides/create-query-client-options.js'
+        create-predefined-parameters-request-fn:
+          '@openapi-qraft/react':
+            RequestFn: '../type-overrides/qraft-predefined-parameters.js'
+          '@openapi-qraft/react/qraftPredefinedParametersRequestFn':
+            QraftPredefinedParameterValue: '../type-overrides/qraft-predefined-parameters.js'
   files:
     root: ../test-fixtures/openapi.json
     x-openapi-qraft:
-      plugin:
-        tanstack-query-react: true
-        openapi-typescript: true
       output-dir: src/tests/fixtures/files-api
       clean: true
       openapi-types-file-name: internal-openapi.ts

packages/react-client/src/tests/fixtures/type-overrides/create-query-client-options.ts

@@ -0,0 +1 @@
+export type { CreateAPIQueryClientOptions } from '@openapi-qraft/react';

packages/react-client/src/tests/fixtures/type-overrides/operation-error.ts

@@ -0,0 +1 @@
+export type { OperationError } from '@openapi-qraft/tanstack-query-react-types';

packages/react-client/src/tests/fixtures/type-overrides/qraft-predefined-parameters.ts

@@ -0,0 +1,2 @@
+export type { RequestFn } from '@openapi-qraft/react';
+export type { QraftPredefinedParameterValue } from '@openapi-qraft/react/qraftPredefinedParametersRequestFn';

packages/react-client/src/tests/fixtures/type-overrides/suspense-query.ts

@@ -0,0 +1,4 @@
+export type {
+  UseSuspenseQueryOptions,
+  UseSuspenseQueryResult,
+} from '@tanstack/react-query';

packages/react-client/src/tests/fixtures/type-overrides/use-infinite-query-result.ts

@@ -0,0 +1 @@
+export type { UseInfiniteQueryResult } from '@tanstack/react-query';