hey-api · mrlubos · Aug 20, 2025 · Aug 20, 2025
diff --git a/.changeset/twelve-mice-cheer.md b/.changeset/twelve-mice-cheer.md
@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+feat(parser): input supports Scalar API Registry with `scalar:` prefix
diff --git a/docs/openapi-ts/configuration/input.md b/docs/openapi-ts/configuration/input.md
@@ -104,6 +104,17 @@ export default {
 
 We also provide shorthands for other registries:
 
+::: details Scalar
+Prefix your input with `scalar:` to use the Scalar API Registry.
+
+```js [long]
+export default {
+  input: 'scalar:@scalar/access-service', // [!code ++]
+};
+```
+
+:::
+
 ::: details ReadMe
 Prefix your input with `readme:` to use the ReadMe API Registry.
 

diff --git a/...napi-ts-axios/src/client/client/client.ts → ...-ts-axios/src/client/client/client.gen.ts b/...napi-ts-axios/src/client/client/client.ts → ...-ts-axios/src/client/client/client.gen.ts
@@ -1,21 +1,29 @@
-import type { AxiosError, RawAxiosRequestHeaders } from 'axios';
+// This file is auto-generated by @hey-api/openapi-ts
+
+import type { AxiosError, AxiosInstance, RawAxiosRequestHeaders } from 'axios';
 import axios from 'axios';
 
-import type { Client, Config } from './types';
+import type { Client, Config } from './types.gen';
 import {
   buildUrl,
   createConfig,
   mergeConfigs,
   mergeHeaders,
   setAuthParams,
-} from './utils';
+} from './utils.gen';
 
 export const createClient = (config: Config = {}): Client => {
   let _config = mergeConfigs(createConfig(), config);
 
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { auth, ...configWithoutAuth } = _config;
-  const instance = axios.create(configWithoutAuth);
+  let instance: AxiosInstance;
+
+  if (_config.axios && !('Axios' in _config.axios)) {
+    instance = _config.axios;
+  } else {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { auth, ...configWithoutAuth } = _config;
+    instance = axios.create(configWithoutAuth);
+  }
 
   const getConfig = (): Config => ({ ..._config });
 
@@ -46,6 +54,10 @@ export const createClient = (config: Config = {}): Client => {
       });
     }
 
+    if (opts.requestValidator) {
+      await opts.requestValidator(opts);
+    }
+
     if (opts.body && opts.bodySerializer) {
       opts.body = opts.bodySerializer(opts.body);
     }

diff --git a/examples/openapi-ts-axios/src/client/client/index.ts b/examples/openapi-ts-axios/src/client/client/index.ts
@@ -1,12 +1,14 @@
-export type { Auth } from '../core/auth';
-export type { QuerySerializerOptions } from '../core/bodySerializer';
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { Auth } from '../core/auth.gen';
+export type { QuerySerializerOptions } from '../core/bodySerializer.gen';
 export {
   formDataBodySerializer,
   jsonBodySerializer,
   urlSearchParamsBodySerializer,
-} from '../core/bodySerializer';
-export { buildClientParams } from '../core/params';
-export { createClient } from './client';
+} from '../core/bodySerializer.gen';
+export { buildClientParams } from '../core/params.gen';
+export { createClient } from './client.gen';
 export type {
   Client,
   ClientOptions,
@@ -17,5 +19,5 @@ export type {
   RequestOptions,
   RequestResult,
   TDataShape,
-} from './types';
-export { createConfig } from './utils';
+} from './types.gen';
+export { createConfig } from './utils.gen';
diff --git a/...enapi-ts-axios/src/client/client/types.ts → ...i-ts-axios/src/client/client/types.gen.ts b/...enapi-ts-axios/src/client/client/types.ts → ...i-ts-axios/src/client/client/types.gen.ts
@@ -1,24 +1,30 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
 import type {
   AxiosError,
   AxiosInstance,
+  AxiosRequestHeaders,
   AxiosResponse,
   AxiosStatic,
   CreateAxiosDefaults,
 } from 'axios';
 
-import type { Auth } from '../core/auth';
-import type { Client as CoreClient, Config as CoreConfig } from '../core/types';
+import type { Auth } from '../core/auth.gen';
+import type {
+  Client as CoreClient,
+  Config as CoreConfig,
+} from '../core/types.gen';
 
 export interface Config<T extends ClientOptions = ClientOptions>
   extends Omit<CreateAxiosDefaults, 'auth' | 'baseURL' | 'headers' | 'method'>,
     CoreConfig {
   /**
-   * Axios implementation. You can use this option to provide a custom
-   * Axios instance.
+   * Axios implementation. You can use this option to provide either an
+   * `AxiosStatic` or an `AxiosInstance`.
    *
    * @default axios
    */
-  axios?: AxiosStatic;
+  axios?: AxiosStatic | AxiosInstance;
   /**
    * Base URL for all requests made by this client.
    */
@@ -30,7 +36,7 @@ export interface Config<T extends ClientOptions = ClientOptions>
    * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
    */
   headers?:
-    | CreateAxiosDefaults['headers']
+    | AxiosRequestHeaders
     | Record<
         string,
         | string

diff --git a/...enapi-ts-axios/src/client/client/utils.ts → ...i-ts-axios/src/client/client/utils.gen.ts b/...enapi-ts-axios/src/client/client/utils.ts → ...i-ts-axios/src/client/client/utils.gen.ts
@@ -1,15 +1,22 @@
-import { getAuthToken } from '../core/auth';
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { getAuthToken } from '../core/auth.gen';
 import type {
   QuerySerializer,
   QuerySerializerOptions,
-} from '../core/bodySerializer';
-import type { ArraySeparatorStyle } from '../core/pathSerializer';
+} from '../core/bodySerializer.gen';
+import type { ArraySeparatorStyle } from '../core/pathSerializer.gen';
 import {
   serializeArrayParam,
   serializeObjectParam,
   serializePrimitiveParam,
-} from '../core/pathSerializer';
-import type { Client, ClientOptions, Config, RequestOptions } from './types';
+} from '../core/pathSerializer.gen';
+import type {
+  Client,
+  ClientOptions,
+  Config,
+  RequestOptions,
+} from './types.gen';
 
 interface PathSerializer {
   path: Record<string, unknown>;
@@ -138,6 +145,28 @@ export const createQuerySerializer = <T = unknown>({
   return querySerializer;
 };
 
+const checkForExistence = (
+  options: Pick<RequestOptions, 'auth' | 'query'> & {
+    headers: Record<any, unknown>;
+  },
+  name?: string,
+): boolean => {
+  if (!name) {
+    return false;
+  }
+  if (name in options.headers || options.query?.[name]) {
+    return true;
+  }
+  if (
+    'Cookie' in options.headers &&
+    options.headers['Cookie'] &&
+    typeof options.headers['Cookie'] === 'string'
+  ) {
+    return options.headers['Cookie'].includes(`${name}=`);
+  }
+  return false;
+};
+
 export const setAuthParams = async ({
   security,
   ...options
@@ -146,6 +175,9 @@ export const setAuthParams = async ({
     headers: Record<any, unknown>;
   }) => {
   for (const auth of security) {
+    if (checkForExistence(options, auth.name)) {
+      continue;
+    }
     const token = await getAuthToken(auth, options.auth);
 
     if (!token) {
@@ -175,8 +207,6 @@ export const setAuthParams = async ({
         options.headers[name] = token;
         break;
     }
-
-    return;
   }
 };
 

diff --git a/.../openapi-ts-axios/src/client/core/auth.ts → ...napi-ts-axios/src/client/core/auth.gen.ts b/.../openapi-ts-axios/src/client/core/auth.ts → ...napi-ts-axios/src/client/core/auth.gen.ts
@@ -1,3 +1,5 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
 export type AuthToken = string | undefined;
 
 export interface Auth {

diff --git a/...s-axios/src/client/core/bodySerializer.ts → ...ios/src/client/core/bodySerializer.gen.ts b/...s-axios/src/client/core/bodySerializer.ts → ...ios/src/client/core/bodySerializer.gen.ts
@@ -1,8 +1,10 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
 import type {
   ArrayStyle,
   ObjectStyle,
   SerializerOptions,
-} from './pathSerializer';
+} from './pathSerializer.gen';
 
 export type QuerySerializer = (query: Record<string, unknown>) => string;
 
@@ -14,9 +16,15 @@ export interface QuerySerializerOptions {
   object?: SerializerOptions<ObjectStyle>;
 }
 
-const serializeFormDataPair = (data: FormData, key: string, value: unknown) => {
+const serializeFormDataPair = (
+  data: FormData,
+  key: string,
+  value: unknown,
+): void => {
   if (typeof value === 'string' || value instanceof Blob) {
     data.append(key, value);
+  } else if (value instanceof Date) {
+    data.append(key, value.toISOString());
   } else {
     data.append(key, JSON.stringify(value));
   }
@@ -26,7 +34,7 @@ const serializeUrlSearchParamsPair = (
   data: URLSearchParams,
   key: string,
   value: unknown,
-) => {
+): void => {
   if (typeof value === 'string') {
     data.append(key, value);
   } else {
@@ -37,7 +45,7 @@ const serializeUrlSearchParamsPair = (
 export const formDataBodySerializer = {
   bodySerializer: <T extends Record<string, any> | Array<Record<string, any>>>(
     body: T,
-  ) => {
+  ): FormData => {
     const data = new FormData();
 
     Object.entries(body).forEach(([key, value]) => {
@@ -56,16 +64,16 @@ export const formDataBodySerializer = {
 };
 
 export const jsonBodySerializer = {
-  bodySerializer: <T>(body: T) =>
-    JSON.stringify(body, (key, value) =>
+  bodySerializer: <T>(body: T): string =>
+    JSON.stringify(body, (_key, value) =>
       typeof value === 'bigint' ? value.toString() : value,
     ),
 };
 
 export const urlSearchParamsBodySerializer = {
   bodySerializer: <T extends Record<string, any> | Array<Record<string, any>>>(
     body: T,
-  ) => {
+  ): string => {
     const data = new URLSearchParams();
 
     Object.entries(body).forEach(([key, value]) => {

diff --git a/...penapi-ts-axios/src/client/core/params.ts → ...pi-ts-axios/src/client/core/params.gen.ts b/...penapi-ts-axios/src/client/core/params.ts → ...pi-ts-axios/src/client/core/params.gen.ts
@@ -1,13 +1,25 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
 type Slot = 'body' | 'headers' | 'path' | 'query';
 
 export type Field =
   | {
       in: Exclude<Slot, 'body'>;
+      /**
+       * Field name. This is the name we want the user to see and use.
+       */
       key: string;
+      /**
+       * Field mapped name. This is the name we want to use in the request.
+       * If omitted, we use the same value as `key`.
+       */
       map?: string;
     }
   | {
       in: Extract<Slot, 'body'>;
+      /**
+       * Key isn't required for bodies.
+       */
       key?: string;
       map?: string;
     };

diff --git a/...s-axios/src/client/core/pathSerializer.ts → ...ios/src/client/core/pathSerializer.gen.ts b/...s-axios/src/client/core/pathSerializer.ts → ...ios/src/client/core/pathSerializer.gen.ts
@@ -1,3 +1,5 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
 interface SerializeOptions<T>
   extends SerializePrimitiveOptions,
     SerializerOptions<T> {}

diff --git a/...openapi-ts-axios/src/client/core/types.ts → ...api-ts-axios/src/client/core/types.gen.ts b/...openapi-ts-axios/src/client/core/types.ts → ...api-ts-axios/src/client/core/types.gen.ts
@@ -1,9 +1,11 @@
-import type { Auth, AuthToken } from './auth';
+// This file is auto-generated by @hey-api/openapi-ts
+
+import type { Auth, AuthToken } from './auth.gen';
 import type {
   BodySerializer,
   QuerySerializer,
   QuerySerializerOptions,
-} from './bodySerializer';
+} from './bodySerializer.gen';
 
 export interface Client<
   RequestFn = never,
@@ -84,6 +86,12 @@ export interface Config {
    * {@link https://swagger.io/docs/specification/serialization/#query View examples}
    */
   querySerializer?: QuerySerializer | QuerySerializerOptions;
+  /**
+   * A function validating request data. This is useful if you want to ensure
+   * the request conforms to the desired shape, so it can be safely sent to
+   * the server.
+   */
+  requestValidator?: (data: unknown) => Promise<unknown>;
   /**
    * A function transforming response data before it's returned. This is useful
    * for post-processing data, e.g. converting ISO strings into Date objects.
@@ -96,3 +104,17 @@ export interface Config {
    */
   responseValidator?: (data: unknown) => Promise<unknown>;
 }
+
+type IsExactlyNeverOrNeverUndefined<T> = [T] extends [never]
+  ? true
+  : [T] extends [never | undefined]
+    ? [undefined] extends [T]
+      ? false
+      : true
+    : false;
+
+export type OmitNever<T extends Record<string, unknown>> = {
+  [K in keyof T as IsExactlyNeverOrNeverUndefined<T[K]> extends true
+    ? never
+    : K]: T[K];
+};