Skip to main content
OpenAPI TypeScript can generate type-safe hooks, composables, and query helpers that integrate with popular data fetching libraries. This eliminates manual setup and ensures your API calls stay in sync with your OpenAPI specification.

​
Supported Libraries

OpenAPI TypeScript supports multiple state management and data fetching libraries across different frameworks:

TanStack Query

React, Vue, Svelte, Solid, and Angular support for queries, mutations, and infinite queries.

Pinia Colada

Vue composables for queries and mutations with type-safe query keys.

​
How It Works

State management plugins analyze your OpenAPI specification and generate:
  1. Query Options - Pre-configured options for fetching data
  2. Mutation Options - Type-safe mutation functions for POST/PUT/DELETE operations
  3. Query Keys - Deterministic cache keys based on operation parameters
  4. Hooks/Composables - Framework-specific functions (optional)

​
Generated Artifacts

​
Query Options

For GET operations, plugins generate query options that include:
  • Query function with proper typing
  • Query key generation
  • Error handling
  • Response type inference
// Generated query options
export const getPetByIdOptions = (options: Options<GetPetByIdData>) =>
  queryOptions({
    queryFn: async ({ queryKey, signal }) => {
      const { data } = await client.getPetById({
        ...options,
        ...queryKey[0],
        signal,
        throwOnError: true,
      });
      return data;
    },
    queryKey: getPetByIdQueryKey(options),
  });

​
Mutation Options

For POST/PUT/DELETE operations, plugins generate mutation options: 
// Generated mutation options
export const addPetMutation = (
  options?: Partial<Options<AddPetData>>
) => ({
  mutationFn: async (fnOptions) => {
    const { data } = await client.addPet({
      ...options,
      ...fnOptions,
      throwOnError: true,
    });
    return data;
  },
});

​
Query Keys

Deterministic cache keys are generated for each operation: 
// Generated query key function
export const getPetByIdQueryKey = (options: Options<GetPetByIdData>) =>
  createQueryKey('getPetById', options);

​
Configuration Options

All state management plugins share common configuration patterns:

​
Naming Conventions

Customize how generated functions are named: 
export default defineConfig({
  plugins: [
    {
      name: '@tanstack/react-query',
      // Default: '{{name}}Options'
      queryOptions: '{{name}}QueryOptions',
      // Default: '{{name}}Mutation'
      mutationOptions: '{{name}}MutationOptions',
      // Default: '{{name}}QueryKey'
      queryKeys: '{{name}}Key',
    },
  ],
});

​
Feature Toggles

Enable or disable specific features: 
export default defineConfig({
  plugins: [
    {
      name: '@tanstack/react-query',
      // Disable query keys generation
      queryKeys: false,
      // Enable useQuery hooks
      useQuery: true,
      // Disable infinite queries
      infiniteQueryOptions: false,
    },
  ],
});

​
Query Key Tags

Include operation tags in query keys for better cache invalidation: 
export default defineConfig({
  plugins: [
    {
      name: '@tanstack/react-query',
      queryKeys: {
        tags: true, // Include operation tags
      },
    },
  ],
});

​
Custom Metadata

Add custom metadata to generated options: 
export default defineConfig({
  plugins: [
    {
      name: '@tanstack/react-query',
      queryOptions: {
        meta: (operation) => ({
          operationId: operation.id,
          deprecated: operation.deprecated,
          tags: operation.tags,
        }),
      },
    },
  ],
});

​
Usage Patterns

​
Basic Query

import { useQuery } from '@tanstack/react-query';
import { getPetByIdOptions } from './client/@tanstack/react-query.gen';

function PetDetails({ petId }: { petId: number }) {
  const { data, error, isLoading } = useQuery(
    getPetByIdOptions({
      path: { petId },
    })
  );

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <div>{data.name}</div>;
}

​
Mutations

import { useMutation } from '@tanstack/react-query';
import { addPetMutation } from './client/@tanstack/react-query.gen';

function AddPetForm() {
  const mutation = useMutation(addPetMutation());

  const handleSubmit = (formData: FormData) => {
    mutation.mutate({
      body: {
        name: formData.get('name') as string,
        status: 'available',
      },
    });
  };

  return <form onSubmit={handleSubmit}>{/* form fields */}</form>;
}

​
Next Steps

TanStack Query

Learn about React, Vue, Svelte, Solid, and Angular integration.

Pinia Colada

Explore Vue-specific composables and query management.

Build docs developers (and LLMs) love

Get started for freeTalk to us