openapi-vue-query

A type-safe and lightweight (1kb) wrapper around @tanstack/vue-query for consuming OpenAPI schemas in Vue.js applications.

Built on top of openapi-fetch and openapi-typescript, providing:

- ✅ 100% type-safe - No typos in URLs, params, request bodies, or responses
- ✅ Zero runtime overhead - Types are generated at build time
- ✅ Automatic type inference - No manual typing of your API
- ✅ Eliminates any types that hide bugs
- ✅ Eliminates as type overrides that can hide bugs
- ✅ Vue 3 Composition API support with full reactivity
- ✅ All @tanstack/vue-query features - Caching, background updates, optimistic updates, etc.

🚀 Quick Start

$3

``bash
npm i openapi-vue-query openapi-fetch
npm i -D openapi-typescript typescript
`

$3

Generate TypeScript types from your OpenAPI schema:

`bash
npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
`

$3

`vue



`

🔧 API Reference

$3

For fetching data. Wraps @tanstack/vue-query's useQuery.

`vue

`

$3

For creating, updating, or deleting data. Wraps @tanstack/vue-query's useMutation.

`vue



`

$3

For paginated data. Wraps @tanstack/vue-query's useInfiniteQuery.

`vue



`

$3

For creating reusable query configurations.

`ts
// composables/usePostQuery.ts
export function usePostQuery(postId: Ref) {
return $api.queryOptions("get", "/posts/{id}", {
params: { path: { id: postId } },
});
}

// In component
const postQuery = usePostQuery(postId);
const { data } = useQuery(postQuery);
`

🎯 Advanced Usage

$3

Create reusable API composables:

`ts
// composables/useAuth.ts
export function useAuth() {
const login = $api.useMutation("post", "/auth/login");
const logout = $api.useMutation("post", "/auth/logout");

const { data: user } = $api.useQuery("get", "/auth/me", undefined, {
enabled: computed(() => !!getToken()),
});

return {
user: readonly(user),
login: login.mutate,
logout: logout.mutate,
isLoading: computed(() => login.isPending || logout.isPending),
};
}
`

$3

`vue

`

$3

`ts
import createFetchClient from "openapi-fetch";
import createClient from "openapi-vue-query";

const fetchClient = createFetchClient({
baseUrl: "https://api.example.com/v1",
headers: {
"User-Agent": "MyApp/1.0",
},
});

// Add auth middleware
fetchClient.use({
onRequest({ request }) {
const token = getToken();
if (token) {
request.headers.set("Authorization", Bearer ${token});
}
},
onResponse({ response }) {
if (response.status === 401) {
// Handle unauthorized
logout();
}
},
});

export const $api = createClient(fetchClient);
`

🤝 Integration with Vue Query

openapi-vue-query is fully compatible with @tanstack/vue-query. You can use all vue-query features:

`vue

``

📚 Examples

- Basic CRUD Operations
- Infinite Scroll
- Form Mutations
- Complete Example

🔗 Related Projects

- openapi-fetch - The underlying fetch client
- openapi-typescript - TypeScript code generator
- @tanstack/vue-query - The query library being wrapped

📖 Documentation

For detailed documentation and examples, visit: https://openapi-ts-vue.dev/openapi-vue-query/

🐛 Issues & Feedback

Found a bug or have a feature request? Please open an issue on GitHub.

📄 License

MIT License. See LICENSE for details.