README

react-query-swagger

This projects autogenerates react-query hooks based on Swagger API definitions. So, given that you have a petstore-like API definition, you could autogenerate a list of react-query hooks, to call GET methods from the API (queries). Mutations (POST/PUT/PATCH/DELETE methods) are not yet supported.

This library requires, dotnet runtime (2.1) installed on your machine! If you have .NET Core 3+ or 5+ you'll need to add a switch (e.g. /runtime:Net50) to all commands.

How to add

Install the package into your project using yarn/npm (as a dev-dependency). You'll also need to add react-query (which you probably already have if you are interested in this library).

yarn add -D react-query-swagger

Then create/update your autogenerated hooks by calling (adjusting the URL and output path)

yarn react-query-swagger /input:https://petstore.swagger.io/v2/swagger.json /output:src/api/axios-client.ts /template:Axios

This will generate API clients based on Axios. If you prefer fetch, just use it as a template (mind the last parameter)

yarn react-query-swagger /input:https://petstore.swagger.io/v2/swagger.json /output:src/api/axios-client.ts /template:Fetch

You will probably want to add this script to your package.json to call it every time your API changes.

All parameters are passed to NSwag, you could read about them in NSwag documentation. Personally I tend to use it with few additional parameters:

yarn react-query-swagger /input:https://petstore.swagger.io/v2/swagger.json /output:src/api/axios-client.ts /template:Axios /serviceHost:. /generateConstructorInterface:true /markOptionalProperties:true /generateOptionalParameters:true /nullValue:undefined

How to use

You could check a pet-client example, which shows the list of pets. It's a standard react-query setup, to query some pet data you just need to write:

  const petsQuery = AxiosQuery.ClientQuery.useFindPetsByStatusQuery([
    Status.Available,
    Status.Pending,
    Status.Sold,
  ]);

Configuration

setBaseUrl(baseUrl: string)

Sets base URL for all queries

setAxiosFactory(factory: () => AxiosInstance)

Sets the function which returns Axios instance to be used in http request. By default axios.create() is called for every http request (this method only exists if you generated client using Axios template).

setFetchFactory(factory: () => { fetch(url: RequestInfo, init?: RequestInit): Promise })

Sets the function to return the fetchfunction to be used in http request. By default window is returned, which contains the default fetch function. This method only exists if you used Fetch template.

How to configure queries

You could define additional UseQueryOptions for each query by setting *queryName*DefaultOptions

AxiosQuery.ClientQuery.findPetsByStatusDefaultOptions = {
  cacheTime: 10000
}

How does it work

Under the cover it's just 2 template files for NSwag and a small script to easily use them.

Contributions and support

Issues and Pull Requests are welcome.

For any kind of private consulting or support you could contact Artur Drobinskiy directly via email.

Usage no npm install needed!