|
+ |
|
vue-axios
A small wrapper library for the simple promise based HTTP client axios.
The library is made for Vue 3.x.x and the Composition API.
Instalation
Install the library and axios with npm.
npm install axios @baloise/vue-axios
Use plugin
Import the library into your src/main.ts
file or any other entry point.
import { createApp } from 'vue'
import { vueAxios } from '@baloise/vue-axios'
Apply the library to the vue app instance. The additional configuration have the type AxiosRequestConfig.
const app = createApp(App)
// simple
app.use(vueAxios)
// additional configurations
app.use(vueAxios, {
baseURL: 'http://api.my-site.com',
})
Interceptors
Use the defined $axios
instance. More to the intercepters can be found here.
import { $axios } from '@baloise/vue-axios'
// Add a request interceptor
$axios.interceptors.request.use(
function (config) {
// Do something before request is sent
return config
},
function (error) {
// Do something with request error
return Promise.reject(error)
},
)
// Add a response interceptor
$axios.interceptors.response.use(
function (response) {
// Any status code that lie within the range of 2xx cause this function to trigger
// Do something with response data
return response
},
function (error) {
// Any status codes that falls outside the range of 2xx cause this function to trigger
// Do something with response error
return Promise.reject(error)
},
)
Usage
Have multiple API's
To access multiple apis in your app it could be help full to create a new axios instance. However, if you only access one api configure it through the plugin options defaults
.
Export the new instance and use it in any component.
import { $axios } from '@baloise/vue-axios'
export const catApi = $axios.create({
baseURL: 'https://cat-fact.herokuapp.com',
})
export const dogApi = $axios.create({
baseURL: 'https://dog-fact.herokuapp.com',
})
Use the defined api instance in your components with the same interface that axios has.
catApi.get('/facts')
dogApi.post('/facts', {
fact: 'wuff',
})
Composition API
To use axios with the composition API import the useAxios
composable function. useAxios
return reactive values like isLoading
or functions like request
to execute a HTTP request.
The reactive values gets updated when executing a HTTP request.
import { computed, defineComponent } from 'vue'
import { useAxios } from '@baloise/vue-axios'
import { CatApi } from '../api/cat.api'
type CatFacts = { text: string }[]
export default defineComponent({
setup() {
const { get, data, isLoading, isSuccessful } = useAxios<CatFacts, undefined>(CatApi)
function callApi() {
get('/facts')
}
return {
callApi,
data,
isLoading,
isSuccessful,
}
},
})
useAxios
The useAxios
function accepts a custom axios instance, otherwise it uses the global $axios
instance.
The $axios
instance is defined in the plugin options with the default config.
import { useAxios } from '@baloise/vue-axios'
useAxios()
useAxios(axiosInstance)
Reactive State
The useAxios
function exposes the following reactive state.
import { useAxios } from '@baloise/vue-axios'
const {
data,
error,
headers,
status,
statusText,
abortMessage,
// state
isFinished,
isLoading,
isSuccessful,
hasFailed,
aborted,
} = useAxios()
State | Type | Description |
---|---|---|
data | any |
data is the response that was provided by the server. |
error | any |
Promise Error. |
headers | any |
headers the HTTP headers that the server responded with. |
status | number |
status is the HTTP status code from the server response. |
statusText | string |
statusText is the HTTP status message from the server response. |
abortMessage | string |
abortMessage is the provided message of the abort action. |
isFinished | boolean |
If true the response of the http call is finished. |
isLoading | boolean |
If true the response of the http call is still pending. |
isSuccessful | boolean |
If true the response successfully arrived. |
hasFailed | boolean |
If true the response has failed. |
aborted | boolean |
If true the request has been aborted by the user. |
Functions
The useAxios
function exposes the following functions.
import { useAxios } from '@baloise/vue-axios'
const { request, get, post, put, patch, remove, head, options, abort } = useAxios()
request
Similar to the axios.request
function. Moreover, besides the AxiosRequestConfig
it also accepts Promise<RequestArgs>
paramter too. Promise<RequestArgs>
is the return type of the OpenAPI Codegen ParamCreator.
request(config: AxiosRequestConfig)
request(config: Promise<RequestArgs>)
get, post, put, patch, head, options, remove
Similar to the axios
functions.
get(url[, config])
remove(url[, config])
head(url[, config])
options(url[, config])
post(url[, data[, config]])
put(url[, data[, config]])
patch(url[, data[, config]])
abort
aborts the HTTP request.
abort()
abort(message: string)
Open API Codegen
If your API uses Swagger and follows the OpenApi guidlines it is possible to generate a typescript axios SDK out of it.
To generate a SDK install the OpenAPI Generator
npm add -D @openapitools/openapi-generator-cli
Export the swagger.json
or swagger.yaml
from your API and run the following command.
openapi-generator-cli generate -i path-to/swagger.yaml -g typescript-axios -o generated-sources/openapi --additional-properties=supportsES6=true,npmVersion=6.9.0,withInterfaces=true
Move the generated SDK code into your project. Then define the base configuration of your API and for each endpoint create the param creator.
Have a look into our awesome @baloise/vue-keycloak library.
import { Configuration, UsersApiAxiosParamCreator } from './generated'
import { getToken } from '@baloise/vue-keycloak'
const myApiConfiguration = new Configuration({
basePath: '/my/api',
apiKey: async () => {
const token = await getToken()
return `Bearer ${token}`
},
})
export const UsersApi = UsersApiAxiosParamCreator(myApiConfiguration)
Import the param creator UsersApi
into the component and use them with the function request
to send the HTTP request to the defined API.
import { defineComponent, ref } from 'vue'
import { UsersApi } from '../api/my.api'
import { useAxios } from '@baloise/vue-axios'
export default defineComponent({
setup() {
const { request } = useAxios()
async function onButtonClick() {
await request(UsersApi.getUserUsingGET('7'))
}
return { onButtonClick }
},
})
License
Apache-2.0 Licensed | Copyright © 2021-present Gery Hirschfeld & Contributors