Vue Integration Tutorial

See the Vue Example for a working demo you can run immediately.

Prerequisites

• Node.js ≥ 18, Vue ≥ 3.3
• ApiSorcery CLI installed (npm i -g @apisorcery/cli)
• Device registered (apisorcery register)
• A .apisorceryrc.json configured for your project (Service Config)

Generated File Structure

After running apisorcery generate, the following files are created under outputDir (e.g. src/api/auto/):

auto/
└── {service_code}/
    ├── Api{Tag}.ts            # One file per Swagger tag — do NOT edit
    ├── model.ts               # All request / response types — do NOT edit
    ├── base.ts                # Base helpers — do NOT edit
    ├── swagger.json           # Cached Swagger spec — do NOT edit
    └── httpClient/
        ├── interceptors/
        │   ├── request.ts     # ✏️ Add auth token here
        │   └── response.ts    # ✏️ Handle global errors here
        ├── requests/
        │   ├── json.ts        # JSON request factory — edit base URL here
        │   └── blob.ts        # File download factory
        └── types/
            └── axios.d.ts

Re-generation

Files marked do NOT edit are overwritten on every apisorcery generate run. Only modify files inside httpClient/interceptors/ and the baseURL in requests/json.ts.

Install Dependencies

npm install axios

Configure Base URL

Open httpClient/requests/json.ts and set your API server address:

const instance = axios.create({
  baseURL: 'https://your-api.com',  // ✏️ change this
  timeout: 10000,
});

Configure Auth Token

Open httpClient/interceptors/request.ts:

instance.interceptors.request.use((config) => {
  const token = localStorage.getItem('token'); // ✏️ use your own token source
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

Open httpClient/interceptors/response.ts to handle auth errors globally:

instance.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // ✏️ redirect to login, e.g. router.push('/login')
    }
    return Promise.reject(error);
  }
);

Using the Generated APIs

<script setup lang="ts">
import { onMounted, ref } from 'vue';
import * as ApiUser from '@/api/auto/demo/ApiUser';
import type { UserInfoDto } from '@/api/auto/demo/model';

const users = ref<UserInfoDto[]>([]);

onMounted(async () => {
  users.value = await ApiUser.getUserList({ page: 1, limit: 10 });
});
</script>

<template>
  <ul>
    <li v-for="user in users" :key="user.id">{{ user.name }}</li>
  </ul>
</template>

Common Issues

returnLevel — which value should I use?

Most backends wrap responses in { code, data, message }. Use "returnLevel": "second" (the default) to unwrap data automatically. If your API returns the payload directly, use "returnLevel": "first".

Chinese tag names generate uncompilable class names

Add a tagNameMap to your service config:

"tagNameMap": { "用户管理": "User", "订单管理": "Order" }

See Service Config for details.