Code Generation

RTK Query's API and architecture is oriented around declaring API endpoints up front. This lends itself well to automatically generating API slice definitions from external API schema definitions, such as OpenAPI and GraphQL.

We have early previews of code generation capabilities available as separate tools.

GraphQL

We provide a Plugin for GraphQL Codegen. You can find the documentation to that on the graphql-codegen homepage.

For a full example on how to use it, you can see this example project.

OpenAPI

We provide a package for RTK Query code generation from OpenAPI schemas. It is published as @rtk-query/codegen-openapi and you can find the source code at packages/rtk-query-codegen-openapi.

Usage

Create an empty api using createApi like

src/store/emptyApi.ts

// Or from '@reduxjs/toolkit/query' if not using the auto-generated hooks
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

// initialize an empty api service that we'll inject endpoints into later as needed
export const emptySplitApi = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
  endpoints: () => ({}),
})

Generate a config file (json, js or ts) with contents like

openapi-config.ts

import type { ConfigFile } from '@rtk-query/codegen-openapi'

const config: ConfigFile = {
  schemaFile: 'https://petstore3.swagger.io/api/v3/openapi.json',
  apiFile: './src/store/emptyApi.ts',
  apiImport: 'emptySplitApi',
  outputFile: './src/store/petApi.ts',
  exportName: 'petApi',
  hooks: true,
}

export default config

and then call the code generator:

npx @rtk-query/codegen-openapi openapi-config.ts

Generating tags

If your OpenAPI specification uses tags, you can specify the tag option to the codegen. That will result in all generated endpoints having providesTags/invalidatesTags declarations for the tags of their respective operation definition.

Note that this will only result in string tags with no ids, so it might lead to scenarios where too much is invalidated and unneccessary requests are made on mutation.

In that case it is still recommended to manually specify tags by using enhanceEndpoints on top of the generated api and manually declare providesTags/invalidatesTags.

Programmatic usage

src/store/petApi.ts

import { generateEndpoints } from '@rtk-query/codegen-openapi'

const api = await generateEndpoints({
  apiFile: './fixtures/emptyApi.ts',
  schemaFile: resolve(__dirname, 'fixtures/petstore.json'),
  filterEndpoints: ['getPetById', 'addPet'],
  hooks: true,
})

Config file options

Simple usage

interface SimpleUsage {
  apiFile: string
  schemaFile: string
  apiImport?: string
  exportName?: string
  argSuffix?: string
  operationNameSuffix?: string
  responseSuffix?: string
  hooks?:
    | boolean
    | { queries: boolean; lazyQueries: boolean; mutations: boolean }
  tag?: boolean
  outputFile: string
  filterEndpoints?:
    | string
    | RegExp
    | EndpointMatcherFunction
    | Array<string | RegExp | EndpointMatcherFunction>
  endpointOverrides?: EndpointOverrides[]
  flattenArg?: boolean
  useEnumType?: boolean
  httpResolverOptions?: SwaggerParser.HTTPResolverOptions
}

export type EndpointMatcherFunction = (
  operationName: string,
  operationDefinition: OperationDefinition,
) => boolean

Filtering endpoints

If you only want to include a few endpoints, you can use the filterEndpoints config option to filter your endpoints. Note that endpoints are transformed to camel case. For example, login_user will become loginUser. filterEndpoints will be checked against this camel case version of the endpoint.

openapi-config.ts

const filteredConfig: ConfigFile = {
  // ...
  // should only have endpoints loginUser, placeOrder, getOrderById, deleteOrder
  filterEndpoints: ['loginUser', /Order/],
}

Endpoint overrides

If an endpoint is generated as a mutation instead of a query or the other way round, you can override that:

openapi-config.ts

const withOverride: ConfigFile = {
  // ...
  endpointOverrides: [
    {
      pattern: 'loginUser',
      type: 'mutation',
    },
  ],
}

You can also filter the parameters that are included for an endpoint, as long as they aren't a path parameter. This filter is of type ParameterMatcher. For example, to only include parameters that begin with "x-" for the 'loginUser' endpoint, see the below example.

openapi-config.ts

const withOverride: ConfigFile = {
  // ...
  endpointOverrides: [
    {
      pattern: 'loginUser',
      parameterFilter: /^x-/,
    },
  ],
}

For more complex requirements, consider the other possible matchers, such as a ParameterMatcherFunction. The below example filters out any parameters that are in the header of the request.

openapi-config.ts

const withOverride: ConfigFile = {
  // ...
  endpointOverrides: [
    {
      pattern: /.*/,
      parameterFilter: (_name, parameter) => parameter.in !== 'header',
    },
  ],
}

Generating hooks

Setting hooks: true will generate useQuery and useMutation hook exports. If you also want useLazyQuery hooks generated or more granular control, you can also pass an object in the shape of: { queries: boolean; lazyQueries: boolean; mutations: boolean }.

Multiple output files

openapi-config.ts

const config: ConfigFile = {
  schemaFile: 'https://petstore3.swagger.io/api/v3/openapi.json',
  apiFile: './src/store/emptyApi.ts',
  outputFiles: {
    './src/store/user.ts': {
      filterEndpoints: [/user/i],
    },
    './src/store/order.ts': {
      filterEndpoints: [/order/i],
    },
    './src/store/pet.ts': {
      filterEndpoints: [/pet/i],
    },
  },
}

Custom HTTP resolver options

If you need to customize the HTTP request issued to your server, you user the httpResolverOptions option. This object is passed directly to the SwaggerParser instance that fetches the OpenAPI schema.

For example, you can pass custom headers or set a custom request timeout.

openapi-config.ts

const config: ConfigFile = {
  schemaFile: 'https://petstore3.swagger.io/api/v3/openapi.json',
  apiFile: './src/store/emptyApi.ts',
  outputFile: './src/store/petApi.ts',
  httpResolverOptions: {
    timeout: 30_000,
    headers: {
      Accept: 'application/json',
      Authorization: 'Basic cmVkdXgtdG9vbGtpdDppcy1ncmVhdA==',
    },
  },
}