Quick Start

To get started with OpenAPI Qraft, you first need to generate types from your OpenAPI Document, and also generate services that will use these types to interact with your API.

1. Generate OpenAPI Types & Services

Assumed that you already installed @openapi-qraft/react package ✅

Instant CLI

Run the following command in the root directory of your project using your package manager.

npx @openapi-qraft/cli@next --plugin tanstack-query-react --plugin openapi-typescript \
  --output-dir src/api https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml

package.json setup

Add the following scripts and devDependencies to your package.json:

{
  "scripts": {
    "generate-client": "openapi-qraft --plugin tanstack-query-react --plugin openapi-typescript https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml --output-dir src/api"
  },
  "devDependencies": {
    "@openapi-qraft/cli": "latest"
  },
  "dependencies": {
    "@openapi-qraft/react": "latest"
  }
}

Then run the following command in the root directory of your project:

npm

npm install
npm run generate-client

yarn

yarn install
yarn generate-client

pnpm

pnpm install
pnpm run generate-client

info

openapi-qraft creates service files in the src/api directory of your project:

src/
├── api/
│ ├── schema.d.ts          # ⬅︎ Types generated by `--plugin openapi-typescript`
│ │                        # ⬇︎ Files generated by `--plugin tanstack-query-react`
│ ├── create-api-client.ts # Generated function to create the API client
│ └── services/            # Generated services
│   ├── PetService.ts
│   ├── StoreService.ts
│   └── UserService.ts

• --clean option could be useful. With the option, src/api/services directory will be cleared before the new services are generated.

2. Use the generated services in your React application

Here are examples of how to use the generated services in your React application with useQuery, useMutation, and useInfiniteQuery hooks from TanStack Query.

useQuery(...)

src/App.tsx

import { createAPIClient } from './api'; // generated by OpenAPI Qraft

import { requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

// Use `createAPIClient(...)` to initialize the API client as needed.
// It's a lightweight 🪶 shortcut for working with TanStack Query 🌴
const api = createAPIClient({
  requestFn,
  queryClient,
  baseUrl: 'https://petstore3.swagger.io/api/v3',
});

function ExamplePetDetails({ petId }: { petId: number }) {
  /**
   * Executes the request to the API on mount:
   * ###
   * GET /pet/123456
   **/
  const {
    data: pet,
    isPending,
    error,
  } = api.pet.getPetById.useQuery({
    path: { petId },
  });

  if (isPending) {
    return <div>Loading...</div>;
  }

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

  return <div>Pet Name: {pet?.name}</div>;
}

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ExamplePetDetails petId={123456} />
    </QueryClientProvider>
  );
}

useMutation(...)

src/App.tsx

import { createAPIClient } from './api'; // generated by OpenAPI Qraft

import { requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

const api = createAPIClient({
  requestFn,
  queryClient,
  baseUrl: 'https://petstore3.swagger.io/api/v3',
});

function EntityForm({ entityId }: { entityId: string }) {
  const mutation = api.entities.postEntitiesIdDocuments.useMutation({
    // ☝️ useMutation() can be used with `undefined` parameters
    path: {
      entity_id: entityId
    },
    header: {
      'x-monite-version': '2023-09-01',
    },
  });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        /**
         * Executes the request`:
         * ###
         * POST /entities/3e3e-3e3e-3e3e/documents
         * x-monite-version: 2023-09-01
         *
         * {"company_tax_id_verification": ["verification-id"]}
         **/
        mutation.mutate({
          company_tax_id_verification: [
            String(formData.get('company_tax_id_verification')),
          ],
        });
      }}
    >
      <input name="company_tax_id_verification" />
      <button>Submit</button>
    </form>
  );
}

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <EntityForm entityId="3e3e-3e3e-3e3e" />
    </QueryClientProvider>
  );
}

useInfiniteQuery(...)

src/PostList.tsx

import { createAPIClient } from './api'; // generated by OpenAPI Qraft

import { requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

const api = createAPIClient({
  requestFn,
  queryClient,
  baseUrl: 'https://petstore3.swagger.io/api/v3',
});

/**
 * Executes the initial request:
 * ###
 * GET /posts?limit=10&page=1
 **/
function PostList() {
  const infiniteQuery = api.posts.getPosts.useInfiniteQuery(
    { query: { limit: 10 } },
    {
      // * required by TanStack Query
      getNextPageParam: (lastPage, allPages, lastPageParams) => {
        if (lastPage.length < 10) return; // if less than 10 items, there are no more pages
        return {
          query: {
            page: Number(lastPageParams.query?.page) + 1,
          },
        };
      },
      // * required by TanStack Query
      initialPageParam: {
        query: {
          page: 1, // will be used in initial request
        },
      },
    }
  );

  return (
    <div>
      {infiniteQuery.data?.pages.map((page, pageIndex) => (
        <ul key={pageIndex}>
          {page.map((post) => (
            <li key={post.id}>{post.title}</li>
          ))}
        </ul>
      ))}
      <button onClick={() => {
        // ⬇︎ Executes GET /posts?limit=10&page=2
        infiniteQuery.fetchNextPage()
      }}>
        Load More
      </button>
    </div>
  );
}

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <PostList />
    </QueryClientProvider>
  );
}