Package Exports

@web-bee-ru/openapi-axios

Readme

A tiny, type-safe wrapper around axios to add support for full type inference from OpenAPI schema definitions that are generated with OpenAPI-TS.

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

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">(axios, { validStatus: "axios" });
// const api =  new OpenApiAxios<paths>(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

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

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

// 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)