UniApp Integration Tutorial

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

Prerequisites

• HBuilderX or Vite-based UniApp project
• 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        # Uses uni.request — edit base URL here

UniApp vs Web

The UniApp-generated client uses uni.request instead of Axios, so no extra packages need to be installed.

Configure Base URL

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

const BASE_URL = 'https://your-api.com'; // ✏️ change this

Configure Auth Token

Open httpClient/interceptors/request.ts:

export function requestInterceptor(config: UniApp.RequestOptions) {
  const token = uni.getStorageSync('token'); // ✏️ use your own token source
  if (token) {
    config.header = {
      ...config.header,
      Authorization: `Bearer ${token}`,
    };
  }
  return config;
}

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

export function responseInterceptor(response: UniApp.RequestSuccessCallbackResult) {
  if (response.statusCode === 401) {
    // ✏️ redirect to login, e.g. uni.navigateTo({ url: '/pages/login/index' })
  }
  return response;
}

Using the Generated APIs

import * as ApiUser from '@/api/auto/demo/ApiUser';

async function loadUsers() {
  const users = await ApiUser.getUserList({ page: 1, limit: 10 });
  console.log(users);
}

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.