OpenAPI TypeScript

https://openapi-ts.dev/
Admin
OpenAPI TypeScript converts OpenAPI 3.0/3.1 schemas to TypeScript types and creates type-safe...
Tokens:42,038
Snippets:292
Trust Score:7.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Setup and run the docs site with pnpm

Source: https://openapi-ts.dev/README

Install dependencies and start the local development server for the docs site. Requires Node.js and pnpm.

```bash
pnpm i
pnpm run dev
```

--------------------------------

### useInfiniteQuery example with client setup

Source: https://openapi-ts.dev/openapi-react-query/use-infinite-query

Example of using $api.useInfiniteQuery to fetch paginated posts. The component uses getNextPageParam and initialPageParam to load more pages, and the api client is created with openapi-fetch and openapi-react-query.

```tsx
import { $api } from "./api";
const PostList = () => {
  const { data, fetchNextPage, hasNextPage, isFetching } =
    $api.useInfiniteQuery(
      "get",
      "/posts",
      {
        params: {
          query: {
            limit: 10,
          },
        },
      },
      {
        getNextPageParam: (lastPage) => lastPage.nextPage,
        initialPageParam: 0,
      }
    );

  return (
    <div>
      {data?.pages.map((page, i) => (
        <div key={i}>
          {page.items.map((post) => (
            <div key={post.id}>{post.title}</div>
          ))}
        </div>
      ))}
      {hasNextPage && (
        <button onClick={() => fetchNextPage()} disabled={isFetching}>
          {isFetching ? "Loading..." : "Load More"}
        </button>
      )}
    </div>
  );
};

export const App = () => {
  return (
    <ErrorBoundary fallbackRender={({ error }) => `Error: ${error.message}`}>
      <MyComponent />
    </ErrorBoundary>
  );
};
```

```ts
import createFetchClient from "openapi-fetch";
import createClient from "openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
export const $api = createClient(fetchClient);
```

--------------------------------

### Install openapi-fetch and openapi-typescript

Source: https://openapi-ts.dev/openapi-fetch

Install openapi-fetch and the openapi-typescript CLI as a dev dependency. Also installs TypeScript as a dev dependency.

```bash
npm i openapi-fetch
npm i -D openapi-typescript typescript

```

--------------------------------

### Install openapi-react-query and dependencies

Source: https://openapi-ts.dev/openapi-react-query

Install openapi-react-query and openapi-fetch as dependencies, and openapi-typescript and typescript as dev dependencies.

```bash
npm i openapi-react-query openapi-fetch
npm i -D openapi-typescript typescript
```

--------------------------------

### useMutation example with API client setup

Source: https://openapi-ts.dev/openapi-react-query/use-mutation

Shows how to use the useMutation hook in a React component and how to set up the API client with openapi-fetch and openapi-react-query. The component calls the mutation with a body containing the firstname field.

```tsx
import { $api } from "./api";

export const App = () => {
  const { mutate } = $api.useMutation("patch", "/users");

  return (
    <button onClick={() => mutate({ body: { firstname: "John" } })}>
      Update
    </button>
  );
};

```

```ts
import createFetchClient from "openapi-fetch";
import createClient from "openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
export const $api = createClient(fetchClient);

```

--------------------------------

### Install openapi-typescript and typescript

Source: https://openapi-ts.dev/node

Install openapi-typescript and typescript as dev dependencies. Required before using the Node API.

```bash
npm i --save-dev openapi-typescript typescript
```

--------------------------------

### Install openapi-typescript and TypeScript

Source: https://openapi-ts.dev/introduction

Install openapi-typescript and TypeScript as dev dependencies. Requires Node.js 20.x or higher.

```bash
npm i -D openapi-typescript typescript
```

--------------------------------

### useQuery example with openapi-react-query

Source: https://openapi-ts.dev/openapi-react-query/use-query

Example of using `$api.useQuery` in a React component with a typed fetch client. The `src/api.ts` file creates the client from an OpenAPI schema and is required for the component to work.

```tsx
import { $api } from "./api";

export const App = () => {
  const { data, error, isLoading } = $api.useQuery("get", "/users/{user_id}", {
    params: {
      path: { user_id: 5 },
    },
  });

  if (!data || isLoading) return "Loading...";
  if (error) return `An error occured: ${error.message}`;

  return <div>{data.firstname}</div>;
};
```

```ts
import createFetchClient from "openapi-fetch";
import createClient from "openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
export const $api = createClient(fetchClient);
```

--------------------------------

### useQuery example rewritten using queryOptions

Source: https://openapi-ts.dev/openapi-react-query/query-options

Shows how to use $api.queryOptions with useQuery to fetch a user by ID. The query options are passed directly to useQuery, and the data, error, and isLoading states are handled.

```tsx
import { useQuery } from '@tanstack/react-query';
import { $api } from "./api";

export const App = () => {
  const { data, error, isLoading } = useQuery(
    $api.queryOptions("get", "/users/{user_id}", {
      params: {
        path: { user_id: 5 },
      },
    }),
  );

  if (!data || isLoading) return "Loading...";
  if (error) return `An error occured: ${error.message}`;

  return <div>{data.firstname}</div>;
};
```

```ts
import createFetchClient from "openapi-fetch";
import createClient from "openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
export const $api = createClient(fetchClient);
```

--------------------------------

### Basic client usage with createClient and GET/PUT requests

Source: https://openapi-ts.dev/openapi-fetch

Creates a typed client with createClient<paths>() and makes GET and PUT requests. The path must match the schema literally, and params are grouped by type (path/query) or provided as a body object.

```typescript
import createClient from "openapi-fetch";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });

const { data, error } = await client.GET("/blogposts/{post_id}", {
  params: {
    path: { post_id: "my-post" },
    query: { version: 2 },
  },
});

const { data, error } = await client.PUT("/blogposts", {
  body: {
    title: "New Post",
    body: "<p>New post body</p>",
    publish_date: new Date("2023-03-01T12:00:00Z").getTime(),
  },
});
```

--------------------------------

### GET /blogposts/{post_id}

Source: https://openapi-ts.dev/openapi-fetch

Demonstrates the GET method for fetching a blog post by ID, including path and query parameters.

```APIDOC
## [GET] /blogposts/{post_id}

### Description
Fetches a blog post by its ID. The path parameter `post_id` is required and the query parameter `version` is optional.

### Method
GET

### Endpoint
/blogposts/{post_id}

### Parameters
#### Path Parameters
- **post_id** (string) - Required - The ID of the blog post.

#### Query Parameters
- **version** (number) - Optional - The version of the blog post to retrieve.

### Request Example
```ts
const { data, error } = await client.GET("/blogposts/{post_id}", {
  params: {
    path: { post_id: "my-post" },
    query: { version: 2 },
  },
});
```

### Response
All methods return an object with **data**, **error**, and **response**.

- **data** - The 2xx response if OK; otherwise `undefined`.
- **error** - The 5xx, 4xx, or `default` response if not OK; otherwise `undefined`.
- **response** - The original `Response` object containing `status`, `headers`, etc.
```

--------------------------------

### Basic GET/PUT requests with openapi-fetch

Source: https://openapi-ts.dev/openapi-fetch

Demonstrates the core usage of openapi-fetch: create a client with a baseUrl, then perform GET and PUT requests with type-safe parameters and bodies. `data` and `error` are only present on 2XX and 4XX/5XX responses respectively. Requires a schema generated by openapi-typescript.

```typescript
import createClient from "openapi-fetch";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });

const {
  data, // only present if 2XX response
  error, // only present if 4XX or 5XX response
} = await client.GET("/blogposts/{post_id}", {
  params: {
    path: { post_id: "123" },
  },
});

await client.PUT("/blogposts", {
  body: {
    title: "My New Post",
  },
});

```

--------------------------------

### Configure authentication headers in redocly.yaml

Source: https://openapi-ts.dev/cli

Configure authentication headers for non-public schemas in a redocly.yaml file. The example adds an X-API-KEY header and an Authorization header, with values read from environment variables SECRET_KEY and SECRET_AUTH respectively.

```yaml
resolve:
  http:
    headers:
      - matches: https://api.example.com/v2/**
        name: X-API-KEY
        envVariable: SECRET_KEY
      - matches: https://example.com/*/test.yaml
        name: Authorization
        envVariable: SECRET_AUTH
```

--------------------------------

### useMutation

Source: https://openapi-ts.dev/openapi-react-query/use-mutation

Documentation for the useMutation hook from openapi-react-query, including its signature, arguments, and usage example.

```APIDOC
## useMutation(method, path, queryOptions, queryClient)

### Description
Allows you to use the original `useMutation` from @tanstack/react-query with OpenAPI integration. The result is the same as the original function, with `mutationKey` set to `[method, path]` and fully typed `data` and `error`.

### Method
`useMutation` (React hook)

### Endpoint
`$api.useMutation(method, path, queryOptions, queryClient)`

### Parameters
- **method** (string) - Required - The HTTP method to use for the request. Used as key.
- **path** (string) - Required - The pathname to use for the request. Must be an available path for the given method in your schema. Used as key.
- **queryOptions** (object) - Optional - The original `useMutation` options.
- **queryClient** (object) - Optional - The original `queryClient` option.

### Request Example
```tsx
const { mutate } = $api.useMutation("patch", "/users");
mutate({ body: { firstname: "John" } });
```

### Response
Returns the same result as the original `useMutation` function, with `data` and `error` fully typed.
```

--------------------------------

### Custom pathSerializer example

Source: https://openapi-ts.dev/openapi-fetch/api

Custom pathSerializer to replace path parameters with a non-standard format, e.g., wrapping values in brackets. The example shows the resulting URL `/users/[5]`.

```ts
const client = createClient({
  pathSerializer(pathname, pathParams) {
    let result = pathname;
    for (const [key, value] of Object.entries(pathParams)) {
      result = result.replace(`{${key}}`, `[${value}]`);
    }
    return result;
  },
});

const { data, error } = await client.GET("/users/{id}", {
  params: { path: { id: 5 } },
});

// URL: `/users/[5]`
```

--------------------------------

### Fetch options

Source: https://openapi-ts.dev/openapi-fetch/api

Options that can be passed to request methods like GET, POST, etc.

```APIDOC
## Fetch options

### Description
Options that apply to all request methods (e.g., .GET(), .POST()).

### Method
GET

### Endpoint
client.GET("/my-url", options)

### Parameters
#### Options
- **params** (ParamsObject) - Optional - path and query params for the endpoint
- **body** ({ [name]:value }) - Optional - requestBody data for the endpoint
- **querySerializer** (QuerySerializer) - Optional - Provide a querySerializer
- **bodySerializer** (BodySerializer) - Optional - Provide a bodySerializer
- **pathSerializer** (PathSerializer) - Optional - Provide a pathSerializer
- **parseAs** ("json" | "text" | "arrayBuffer" | "blob" | "stream") - Optional - Parse the response using a built-in instance method (default: "json"). "stream" skips parsing altogether and returns the raw stream.
- **baseUrl** (string) - Optional - Prefix the fetch URL with this option (e.g. "https://myapi.dev/v1/")
- **fetch** (fetch) - Optional - Fetch instance used for requests (default: fetch from createClient)
- **middleware** (Middleware[]) - Optional - See docs
- **(Fetch options)** - Optional - Any valid fetch option (headers, mode, cache, signal, …)

### Request Example
```ts
client.GET("/my-url", {
  params: { query: { page: 1 } },
  body: { name: "value" },
  parseAs: "json",
  baseUrl: "https://myapi.dev/v1/",
  fetch: customFetch,
  middleware: [myMiddleware],
  headers: { "X-Custom": "value" }
});
```

### Response
#### Success Response
- Returns a promise resolving to the response data.

#### Response Example
```ts
const { data, error } = await client.GET("/my-url", { params: { query: { page: 1 } } });
```
```

--------------------------------

### Middleware

Source: https://openapi-ts.dev/openapi-fetch/api

Defines the Middleware object with onRequest, onResponse, and onError callbacks, including their parameters, return values, and an example.

```APIDOC
## Middleware Object

### Description
Middleware is an object with `onRequest()`, `onResponse()` and `onError()` callbacks that can observe and modify requests, responses and errors.

### Properties
- `onRequest` (function) - Required - Callback that receives `{ request, options }` and can return a `Request`, `Response`, or `undefined`.
- `onResponse` (function) - Required - Callback that receives `{ request, response, options }` and can return a `Response` or `undefined`.
- `onError` (function) - Required - Callback that receives `{ error }` and can return an `Error`, `Response`, or `undefined`.

### Callback Parameters
Each middleware callback receives an `options` object with the following properties:
- `request` (Request) - The current `Request` to be sent to the endpoint.
- `schemaPath` (string) - The original OpenAPI path called (e.g. `/users/{user_id}`).
- `params` (Object) - The original `params` object passed to `GET()` / `POST()` / etc.
- `id` (string) - A random, unique ID for this request.
- `options` (ClientOptions) - The readonly options passed to `createClient()`.

In addition, the `onResponse` callback receives an additional `response` property:
- `response` (Response) - The `Response` returned from the endpoint.

The `onError` callback receives an additional `error` property:
- `error` (unknown) - The error thrown by `fetch`, probably a `TypeError` or a `DOMException`.

### Return Values
- `onRequest`: A `Request` to modify the request, a `Response` to short-circuit the middleware chain, or `undefined` to leave request untouched (skip).
- `onResponse`: Either a `Response` to modify the response, or `undefined` to leave it untouched (skip).
- `onError`: Either an `Error` to modify the error that is thrown, a `Response` which means that the `fetch` call will proceed as successful, or `undefined` to leave the error untouched (skip).

### Example
```ts
import createClient from "openapi-fetch";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const myMiddleware: Middleware = {
  async onRequest({ request, options }) {
    // set "foo" header
    request.headers.set("foo", "bar");
    return request;
  },
  async onResponse({ request, response, options }) {
    const { body, ...resOptions } = res;
    // change status of response
    return new Response(body, { ...resOptions, status: 200 });
  },
  async onError({ error }) {
    // wrap errors thrown by fetch
    return new Error("Oops, fetch failed", { cause: error });
  },
};

const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });

// register middleware
client.use(myMiddleware);
```
```

--------------------------------

### OpenAPI schema with validation constraints

Source: https://openapi-ts.dev/node

Input schema for the transformProperty example, defining a User object with properties name, email, and age, each with validation constraints like minLength, pattern, format, minimum, and maximum.

```yaml
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          pattern: "^[a-zA-Z0-9]+$"
        email:
          type: string
          format: email
        age:
          type: integer
          minimum: 0
          maximum: 120
      required: [name, email]
```

--------------------------------

### Fetch data with openapi-typescript-fetch

Source: https://openapi-ts.dev/examples

Use openapi-typescript-fetch to create a fetcher and define typed GET and PUT operations. Each operation is created with .path().method().create() and invoked with pathParams or body. Errors are caught with try/catch.

```ts
import { Fetcher } from 'openapi-typescript-fetch';
import type { paths } from './my-openapi-3-schema'; // generated by openapi-typescript

const fetcher = Fetcher.for<paths>();

// GET request
const getBlogPost = fetcher.path('/blogposts/{post_id}').method('get').create();

try {
  const { status, data } = await getBlogPost({ pathParams: { post_id: '123' } });
  console.log(data);
} catch (error) {
  console.error('Error:', error);
}

// PUT request
const updateBlogPost = fetcher.path('/blogposts').method('put').create();

try {
  await updateBlogPost({ body: { title: 'My New Post' } });
} catch (error) {
  console.error('Error:', error);
}
```

--------------------------------

### Hono server with openapi-typescript generated types

Source: https://openapi-ts.dev/examples

Use this Hono server example after generating types with openapi-typescript. It demonstrates typed responses for the /users endpoint and typed error responses using the components schema. The code assumes a database query and imports generated types from './my-openapi-3-schema'.

```ts
import { Hono } from "hono";
import { components, paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const app = new Hono();

/** /users */
app.get("/users", async (ctx) => {
  try {
    const users = db.get("SELECT * from users");
    return ctx.json<
      paths["/users"]["responses"][200]["content"]["application/json"]
    >(users);
  } catch (err) {
    return ctx.json<components["schemas"]["Error"]>({
      status: 500,
      message: err ?? "An error occurred",
    });
  }
});

export default app;
```

--------------------------------

### Hono with openapi-ts-router and Zod validation

Source: https://openapi-ts.dev/examples

Use this example to add full type-safety and runtime validation to Hono routes with openapi-ts-router. It wraps a Hono router and uses Zod via validation-adapters to validate path parameters and request bodies. The code imports generated types from './gen/v1' and a custom PetSchema from './schemas'.

```ts
import { Hono } from 'hono';
import { createHonoOpenApiRouter } from 'openapi-ts-router';
import { zValidator } from 'validation-adapters/zod';
import * as z from 'zod';
import { paths } from './gen/v1'; // OpenAPI-generated types
import { PetSchema } from './schemas'; // Custom reusable schema for validation

export const router = new Hono();
export const openApiRouter = createHonoOpenApiRouter<paths>(router);

// GET /pet/{petId}
openApiRouter.get('/pet/{petId}', {
  pathValidator: zValidator(
    z.object({
      petId: z.number() // Validate that petId is a number
    })
  ),
  handler: (c) => {
    const { petId } = c.req.valid('param'); // Access validated params
    return c.json({ name: 'Falko', photoUrls: [] }); 
  }
});

// POST /pet
openApiRouter.post('/pet', {
  bodyValidator: zValidator(PetSchema), // Validate request body using PetSchema
  handler: (c) => {
    const { name, photoUrls } = c.req.valid('json'); // Access validated body data
    return c.json({ name, photoUrls }); 
  }
});

// TypeScript will error if route/method doesn't exist in OpenAPI spec
// or if response doesn't match defined schema
```

--------------------------------

### GET /users/{id}

Source: https://openapi-ts.dev/openapi-fetch/api

Illustrates the default path serialization behavior for GET requests based on OpenAPI 3.1 spec.

```APIDOC
## [GET] /users/{id}

### Description
Retrieves a user. Path serialization follows the OpenAPI 3.1 spec automatically based on the template style.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (any) - Required - The identifier of the user. Can be a primitive, array, or object.

### Response
#### Success Response (200)
The endpoint returns user data. The path is serialized according to the table below:

| Template | Style | Primitive id = 5 | Array id = [3, 4, 5] | Object id = {"role": "admin", "firstName": "Alex"} |
|---|---|---|---|---|
| `/users/{id}` | simple (default) | `/users/5` | `/users/3,4,5` | `/users/role,admin,firstName,Alex` |
| `/users/{id*}` | simple (exploded) | `/users/5` | `/users/3,4,5` | `/users/role=admin,firstName=Alex` |
| `/users/{.id}` | label | `/users/.5` | `/users/.3,4,5` | `/users/.role,admin,firstName,Alex` |
| `/users/{.id*}` | label (exploded) | `/users/.5` | `/users/.3.4.5` | `/users/.role=admin.firstName=Alex` |
| `/users/{;id}` | matrix | `/users/;id=5` | `/users/;id=3,4,5` | `/users/;id=role,admin,firstName,Alex` |
| `/users/{;id*}` | matrix (exploded) | `/users/;id=5` | `/users/;id=3;id=4;id=5` | `/users/;role=admin;firstName=Alex` |

```

--------------------------------

### POST /blogposts

Source: https://openapi-ts.dev/openapi-fetch

Demonstrates the POST method for creating a new blog post with a request body.

```APIDOC
## [POST] /blogposts

### Description
Creates a new blog post. The request body must include the title, body, and publish date.

### Method
POST

### Endpoint
/blogposts

### Parameters
#### Request Body
- **title** (string) - Required - The title of the blog post.
- **body** (string) - Required - The HTML body of the blog post.
- **publish_date** (number) - Required - The publish date as a Unix timestamp in milliseconds.

### Request Example
```ts
const { data, error } = await client.POST("/blogposts", {
  body: {
    title: "New Post",
    body: "<p>New post body</p>",
    publish_date: new Date("2023-03-01T12:00:00Z").getTime(),
  },
});
```

### Response
All methods return an object with **data**, **error**, and **response**.

- **data** - The 2xx response if OK; otherwise `undefined`.
- **error** - The 5xx, 4xx, or `default` response if not OK; otherwise `undefined`.
- **response** - The original `Response` object containing `status`, `headers`, etc.
```

--------------------------------

### $api.useQuery(method, path, options, queryOptions, queryClient)

Source: https://openapi-ts.dev/openapi-react-query/use-query

The useQuery method allows you to use the original useQuery with typed data and error. The query key is [method, path, params]. You can pass query options as the fourth parameter.

```APIDOC
## $api.useQuery(method, path, options, queryOptions, queryClient)

### Description
The `useQuery` method allows you to use the original `useQuery` from @tanstack/react-query. The result is the same as the original function. The query key is `[method, path, params]`. `data` and `error` are fully typed. You can pass query options as the fourth parameter.

### Method
useQuery (hook)

### Endpoint
$api.useQuery(method, path, options, queryOptions, queryClient)

### Parameters
#### Arguments
- **method** (required) - The HTTP method to use for the request. The method is used as key. See Query Keys for more information.
- **path** (required) - The pathname to use for the request. Must be an available path for the given method in your schema. The pathname is used as key. See Query Keys for more information.
- **options** - The fetch options to use for the request. Only required if the OpenApi schema requires parameters. The options `params` are used as key. See Query Keys for more information.
- **queryOptions** - The original `useQuery` options. See more information.
- **queryClient** - The original `queryClient` option. See more information.

### Request Example
tsx
const { data, error, isLoading } = $api.useQuery("get", "/users/{user_id}", {
  params: {
    path: { user_id: 5 },
  },
});


### Response
#### Success Response
The result is the same as the original `useQuery` function. `data` and `error` are fully typed.

#### Response Example
tsx
if (!data || isLoading) return "Loading...";
if (error) return `An error occured: ${error.message}`;
return <div>{data.firstname}</div>;

```

--------------------------------

### useSuspenseQuery example with ErrorBoundary

Source: https://openapi-ts.dev/openapi-react-query/use-suspense-query

Example of using useSuspenseQuery with an ErrorBoundary. The component fetches user data and displays the firstname. The api client is created with openapi-fetch and openapi-react-query, using a generated schema type.

```tsx
import { ErrorBoundary } from "react-error-boundary";
import { $api } from "./api";

const MyComponent = () => {
  const { data } = $api.useSuspenseQuery("get", "/users/{user_id}", {
    params: {
      path: { user_id: 5 },
    },
  });

  return <div>{data.firstname}</div>;
};

export const App = () => {
  return (
    <ErrorBoundary fallbackRender={({ error }) => `Error: ${error.message}`}>
      <MyComponent />
    </ErrorBoundary>
  );
};
```

```ts
import createFetchClient from "openapi-fetch";
import createClient from "openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
export const $api = createClient(fetchClient);
```

--------------------------------

### Basic usage of useQuery with openapi-react-query

Source: https://openapi-ts.dev/openapi-react-query

Create a fetch client with openapi-fetch, wrap it with createClient from openapi-react-query, and use the useQuery hook to fetch a blog post by ID. The component handles loading and error states, returning the post title on success.

```tsx
import createFetchClient from "openapi-fetch";
import createClient from "openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
const $api = createClient(fetchClient);

const MyComponent = () => {
  const { data, error, isLoading } = $api.useQuery(
    "get",
    "/blogposts/{post_id}",
    {
      params: {
        path: { post_id: 5 },
      },
    },
  );

  if (isLoading || !data) return "Loading...";

  if (error) return `An error occured: ${error.message}`;

  return <div>{data.title}</div>;
};
```

--------------------------------

### client.use(middleware)

Source: https://openapi-ts.dev/openapi-fetch/api

Registers middleware to the client.

```APIDOC
## client.use(middleware)

### Description
Registers middleware to the client.

### Parameters
- `middleware` (Middleware) - Required - The middleware object to register.

### Example
```ts
const myMiddleware = {
  // …
};

// register middleware
client.use(myMiddleware);
```
```

--------------------------------

### createClient

Source: https://openapi-ts.dev/openapi-fetch/api

Creates a typed fetch client with default options for all subsequent requests.

```APIDOC
## createClient

### Description
Creates a new API client instance with configurable defaults for all requests.

### Method
createClient

### Endpoint
createClient<paths>(options)

### Parameters
#### Options
- **baseUrl** (string) - Optional - Prefix all fetch URLs with this option (e.g. "https://myapi.dev/v1/")
- **fetch** (fetch) - Optional - Fetch instance used for requests (default: globalThis.fetch)
- **querySerializer** (QuerySerializer) - Optional - Provide a querySerializer
- **bodySerializer** (BodySerializer) - Optional - Provide a bodySerializer
- **pathSerializer** (PathSerializer) - Optional - Provide a pathSerializer
- **(Fetch options)** - Optional - Any valid fetch option (headers, mode, cache, signal …)

### Request Example
```ts
createClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
  fetch: customFetch,
  querySerializer: myQuerySerializer,
  bodySerializer: myBodySerializer,
  pathSerializer: myPathSerializer,
  headers: { "X-Custom": "value" }
});
```

### Response
#### Success Response
- Returns a client instance with methods for each HTTP verb.

#### Response Example
```ts
const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });
```
```

--------------------------------

### Schema for adding optional '?' token

Source: https://openapi-ts.dev/node

Schema with a required binary field, used in the example that adds a '?' token to the property.

```yaml
Body_file_upload:
  type: object;
  properties:
    file:
      type: string;
      format: binary;
      required: true;

```

--------------------------------

### Response object destructuring with GET

Source: https://openapi-ts.dev/openapi-fetch

Shows the shape of the response object returned by all methods, containing data, error, and response fields.

```typescript
const { data, error, response } = await client.GET("/url");
```

--------------------------------

### Configure multiple schemas in redocly.yaml

Source: https://openapi-ts.dev/cli

Define multiple APIs in a redocly.yaml file. Each API has a unique name and optional version, with root as the schema entry point and x-openapi-ts.output for the output file. CLI flags like additional-properties are supported in kebab-case or camelCase.

```yaml
apis:
  core@v2:
    root: ./openapi/openapi.yaml
    x-openapi-ts:
      output: ./openapi/openapi.ts
  external@v1:
    root: ./openapi/external.yaml
    x-openapi-ts:
      output: ./openapi/external.ts
      additional-properties: true # CLI flags are also supported, either in kebab-case or camelCase format
```

--------------------------------

### Schema property with date-time format

Source: https://openapi-ts.dev/node

Example schema property with format date-time. By default openapiTS generates updated_at?: string; because formats are nonstandard.

```yaml
properties:
  updated_at:
    type: string
    format: date-time
```

--------------------------------

### Usage with useQueries

Source: https://openapi-ts.dev/openapi-react-query/query-options

Shows how to use $api.queryOptions with useQueries to fetch multiple users by their IDs. The queries array is built by mapping over userIds and calling queryOptions for each.

```tsx
import { useQueries } from '@tanstack/react-query';
import { $api } from "./api";

export const useUsersById = (userIds: number[]) => (
  useQueries({
    queries: userIds.map((userId) => (
      $api.queryOptions("get", "/users/{user_id}", {
        params: {
          path: { user_id: userId },
        },
      })
    ))
  })
);
```

```ts
import createFetchClient from "openapi-fetch";
import createClient from "openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
export const $api = createClient(fetchClient);
```

--------------------------------

### Transform binary format to Blob type

Source: https://openapi-ts.dev/node

Schema for a file upload body with a binary field. Used in the transform example to generate a `Blob` type.

```yaml
Body_file_upload:
  type: object;
  properties:
    file:
      type: string;
      format: binary;

```

--------------------------------

### $api.useInfiniteQuery(method, path, options, infiniteQueryOptions, queryClient)

Source: https://openapi-ts.dev/openapi-react-query/use-infinite-query

Invokes an infinite query for a given HTTP method and path. The query key is [method, path, params]. Returns the same result as the original useInfiniteQuery, with data and error fully typed.

```APIDOC
## $api.useInfiniteQuery(method, path, options, infiniteQueryOptions, queryClient)

### Description
Invokes an infinite query for a given HTTP method and path. The query key is [method, path, params]. Returns the same result as the original useInfiniteQuery, with data and error fully typed.

### Method
useInfiniteQuery

### Endpoint
$api.useInfiniteQuery(method, path, options, infiniteQueryOptions, queryClient)

### Parameters
#### Arguments
- **method** (string) - Required - The HTTP method to use for the request. The method is used as key. See Query Keys for more information.
- **path** (string) - Required - The pathname to use for the request. Must be an available path for the given method in your schema. The pathname is used as key. See Query Keys for more information.
- **options** (object) - Optional - The fetch options to use for the request. Only required if the OpenApi schema requires parameters. The options `params` are used as key. See Query Keys for more information.
- **infiniteQueryOptions** (object) - Optional - Contains `pageParamName` (string, default `"cursor"`) and the original `useInfiniteQuery` options. See more information.
- **queryClient** (object) - Optional - The original `queryClient` option. See more information.

### Request Example
```tsx
const query = $api.useInfiniteQuery(
  "get",
  "/posts",
  {
    params: {
      query: {
        limit: 10,
      },
    },
  },
  {
    getNextPageParam: (lastPage) => lastPage.nextPage,
    initialPageParam: 0,
  }
);
```

### Response
#### Success Response
Returns the same result as the original `useInfiniteQuery` from @tanstack/react-query. The `data` and `error` are fully typed.

#### Response Example
```tsx
const { data, fetchNextPage, hasNextPage, isFetching } = $api.useInfiniteQuery(
  "get",
  "/posts",
  {
    params: {
      query: {
        limit: 10,
      },
    },
  },
  {
    getNextPageParam: (lastPage) => lastPage.nextPage,
    initialPageParam: 0,
  }
);
```
```

--------------------------------

### Generated TypeScript schema with JSDoc validation annotations

Source: https://openapi-ts.dev/node

Output of the transformProperty example, showing the generated TypeScript interface with JSDoc comments containing validation annotations for each property.

```ts
export interface components {
  schemas: {
    User: {
      /**
       * @minLength 1
       * @pattern ^[a-zA-Z0-9]+$
       */
      name: string;
      /**
       * @format email
       */
      email: string;
      /**
       * @minimum 0
       * @maximum 120
       */
      age?: number;
    };
  };
}
```

--------------------------------

### Dynamic URL type lookup with --path-params-as-types

Source: https://openapi-ts.dev/cli

Shows how enabling --path-params-as-types allows dynamic lookups using the URL variable, automatically matching the schema path.

```typescript
import type { paths } from "./my-openapi-3-schema";

const url = `/user/${id}`;
type UserResponses = paths[url]["responses"]; // automatically matches `paths['/user/{user_id}']`
```

--------------------------------

### Transform to add '?' token to property

Source: https://openapi-ts.dev/node

Custom transform that returns an object with `schema` and `questionToken: true` to make the property optional. Uses the same Blob type logic as the previous example.

```typescript
import openapiTS from "openapi-typescript";
import ts from "typescript";

const BLOB = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("Blob")); // `Blob`
const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull()); // `null`

const ast = await openapiTS(mySchema, {
  transform(schemaObject, metadata) {
    if (schemaObject.format === "binary") {
      return {
        schema: schemaObject.nullable
          ? ts.factory.createUnionTypeNode([BLOB, NULL])
          : BLOB,
        questionToken: true,
      };
    }
  },
});

```

--------------------------------

### Provide a Redoc config to the Node API

Source: https://openapi-ts.dev/node

Provide a fully-initialized Redoc config to the Node API using createConfig() for in-memory config or loadConfig() to load from a redocly.yaml file. The config is passed as the redocly option.

```ts
import { createConfig, loadConfig } from "@redocly/openapi-core";
import openapiTS from "openapi-typescript";

// option 1: create in-memory config
const redocly = await createConfig(
  {
    apis: {
      "core@v2": { … },
      "external@v1": { … },
    },
  },
  { extends: ["recommended"] },
);

// option 2: load from redocly.yaml file
const redocly = await loadConfig({ configPath: "redocly.yaml" });

const ast = await openapiTS(mySchema, { redocly });
```

--------------------------------

### Full form with middlewares and wrapAsPathBasedClient

Source: https://openapi-ts.dev/openapi-fetch/api

Use the full form when you need middlewares. The client reference is shared, so middlewares added after wrapping will propagate to the path-based client.

```ts
const client = createClient<paths>(clientOptions);

client.use(...);

const pathBasedClient = wrapAsPathBasedClient(client);

client.use(...); // the client reference is shared, so the middlewares will propagate.

pathBasedClient["/my-url"].GET(fetchOptions);
```

--------------------------------

### Path-based client with createPathBasedClient

Source: https://openapi-ts.dev/openapi-fetch

Creates a path-based client using createPathBasedClient, allowing selection of the path as a property. Note performance implications and lack of direct middleware attachment.

```typescript
import { createPathBasedClient } from "openapi-fetch";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const client = createPathBasedClient<paths>({
  baseUrl: "https://myapi.dev/v1",
});

client["/blogposts/{post_id}"].GET({
  params: { post_id: "my-post" },
  query: { version: 2 },
});
```

--------------------------------

### $api.queryOptions(method, path, options, queryOptions)

Source: https://openapi-ts.dev/openapi-react-query/query-options

Constructs type-safe Query Options for a given HTTP method and path. The method and path are used as keys, and the options params are also part of the query key. Returns fully typed Query Options with queryKey and queryFn.

```APIDOC
## $api.queryOptions(method, path, options, queryOptions)

### Description
Constructs type-safe Query Options for use with TanStack Query APIs. The method and path are used as keys, and the options params are also part of the query key. Returns fully typed Query Options with queryKey and queryFn.

### Method
queryOptions

### Endpoint
$api.queryOptions(method, path, options, queryOptions)

### Parameters
#### Arguments
- **method** (string) - Required - The HTTP method to use for the request. Used as key.
- **path** (string) - Required - The pathname to use for the request. Must be an available path for the given method in your schema. Used as key.
- **options** (object) - Optional - The fetch options to use for the request. Only required if the OpenAPI schema requires parameters. The options `params` are used as key.
- **queryOptions** (object) - Optional - Additional query options to pass through.

### Returns
- **Query Options** - Fully typed, so `data` and `error` will be correctly deducted. `queryKey` is `[method, path, params]`. `queryFn` is set to a fetcher function.

### Example
```tsx
import { useQuery } from '@tanstack/react-query';
import { $api } from "./api";

export const App = () => {
  const { data, error, isLoading } = useQuery(
    $api.queryOptions("get", "/users/{user_id}", {
      params: {
        path: { user_id: 5 },
      },
    }),
  );

  if (!data || isLoading) return "Loading...";
  if (error) return `An error occured: ${error.message}`;

  return <div>{data.firstname}</div>;
};
```
```

--------------------------------

### Mock fetch requests with vi.fn() in Vitest

Source: https://openapi-ts.dev/openapi-fetch/testing

Use this test to verify that the client sends the correct URL and request body. It supplies a `vi.fn()` mock as the `fetch` option to `createClient`, then inspects the mock's first call after a `PUT` request. Requires Vitest and a generated `paths` type from openapi-typescript.

```ts
import createClient from "openapi-fetch";
import { expect, test, vi } from "vitest";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

test("my request", async () => {
  const mockFetch = vi.fn();
  const client = createClient<paths>({
    baseUrl: "https://my-site.com/api/v1/",
    fetch: mockFetch,
  });

  const reqBody = { name: "test" };
  await client.PUT("/tag", { body: reqBody });

  const req = mockFetch.mock.calls[0][0];
  expect(req.url).toBe("/tag");
  expect(await req.json()).toEqual(reqBody);
});
```

--------------------------------

### Fetch data with openapi-fetch

Source: https://openapi-ts.dev/examples

Use openapi-fetch to create a typed client from your generated paths type. The GET response includes data only for 2XX and error only for 4XX/5XX. The PUT request sends a body with the new post title.

```ts
import createClient from "openapi-fetch";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });

const {
  data, // only present if 2XX response
  error, // only present if 4XX or 5XX response
} = await client.GET("/blogposts/{post_id}", {
  params: {
    path: { post_id: "123" },
  },
});

await client.PUT("/blogposts", {
  body: {
    title: "My New Post",
  },
});
```

--------------------------------

### createPathBasedClient

Source: https://openapi-ts.dev/openapi-fetch/api

Convenience method combining `createClient` and `wrapAsPathBasedClient` if you only want to use the path based call style.

```APIDOC
## createPathBasedClient

### Description
Convenience method combining `createClient` and `wrapAsPathBasedClient` if you only want to use the path based call style.

### Method
N/A (function)

### Endpoint
N/A

### Parameters
- **clientOptions** (object) - Required - Options for the underlying client.

### Request Example
```ts
const client = createPathBasedClient<paths>(clientOptions);

client["/my-url"].GET(fetchOptions);
```

### Response
N/A
```
Tokens:
Raw