@web-bee-ru/openapi-axios/README.md

A TypeScript abstraction over Axios for typed requests generated from OpenAPI (Swagger) schemas using openapi-typescript.

A tiny, type-safe wrapper around [axios](https://axios-http.com) to add support
for full type inference from OpenAPI schema definitions that are generated with
[OpenAPI-TS](https://openapi-ts.dev/introduction).

# API

## Valid status

`validStatus` options configures errors handling strategy and setups returned
value.

Type: `'axios' | 'fetch' | 'all'`

### "axios" mode (default)

Throws error in next cases:

- response.status >= 400
- request failed (e.g. network error)
- axios.interceptors failed

Example

```ts
import { OpenApiAxios } from "@web-bee-ru/openapi-axios";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
import Axios from "axios";

const axios = Axios.create({
  baseURL: "/api",
  adapter: "fetch", // strongly recommended (available since axios@1.7.0)
});

const api = new OpenApiAxios<paths>(axios);
// const api = new OpenApiAxios<paths, "axios">(axios, { validStatus: "axios" }); // same result

try {
  const { status, data, response } = await api.get("/users");
} catch (err) {
  if (api.isAxiosError(err)) {
    if (typeof err.status === "number") {
      // status >= 400
    }
    //  request failed (e.g. network error)
  }
  throw err; // axios.interceptors error
}
```

### "fetch" mode

Throws error in next cases:

- if request failed (e.g. network error)
- axios.interceptors failed

Example

```ts
import { OpenApiAxios } from "@web-bee-ru/openapi-axios";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
import Axios from "axios";

const axios = Axios.create({
  baseURL: "/api",
  adapter: "fetch", // strongly recommended (available since axios@1.7.0)
});

const api = new OpenApiAxios<paths, "fetch">(axios, { validStatus: "fetch" });

try {
  const { status, data, error, response } = await api.get("/users");

  if (error) {
    // status >= 400
  }
} catch (err) {
  if (api.isAxiosError(err)) {
    // request failed (e.g. network error)
  }
  throw err; // axios.interceptors error
}
```

### "all" mode

Never throws error (thus no try/catch required)

Example

```ts
import { OpenApiAxios } from "@web-bee-ru/openapi-axios";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
import Axios from "axios";

const axios = Axios.create({
  baseURL: "/api",
  adapter: "fetch", // strongly recommended (available since axios@1.7.0)
});

const api = new OpenApiAxios<paths, "all">(axios, { validStatus: "all" });

const { status, data, error, response } = await api.get("/users");

if (error) {
  if (typeof status === "number") {
    // status >= 400
  } else if (api.isAxiosError(error)) {
    // request failed (e.g. network error)
  }
  throw error; // axios.interceptors error
}
```

# Comparison

## openapi-fetch vs axios behavior

```ts
// openapi-fetch
// - if 2xx, then { data }
// - if 4xx or 5xx, then { error }
// - if another error (e.g. request failed), then catch

// axios
// - if 2xx, then { data }
// - if 4xx or 5xx, then catch (isAxiosError works)
// - if another error (e.g. request failed), then catch (isAxiosError works)
// - if interceptor error, then catch (isAxiosError DOESN't work)
```

# Other

Special thanks to

- [@IRaccoonI](https://github.com/IRaccoonI) (contributor)
- [@Denwa799](https://github.com/Denwa799) (contributor)
- [@simplesmiler](https://github.com/simplesmiler) (creator of [taxios](https://github.com/simplesmiler/taxios))