HarmonyOS Integration Tutorial

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

Prerequisites

• DevEco Studio ≥ 4.0, HarmonyOS SDK API ≥ 11
• 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. entry/src/main/ets/api/auto/):

auto/
└── {service_code}/
    ├── Api{Tag}.ets           # One file per Swagger tag — do NOT edit
    ├── model.ets              # All request / response types — do NOT edit
    ├── base.ets               # Base helpers — do NOT edit
    └── httpClient/
        ├── interceptors/
        │   ├── request.ets    # ✏️ Add auth token here
        │   └── response.ets   # ✏️ Handle global errors here
        └── requests/
            └── json.ets       # Uses @ohos.net.http — edit base URL here

ArkTS vs TypeScript

HarmonyOS uses ArkTS, a strict superset of TypeScript. The generated client uses @ohos.net.http and requires no third-party packages.

Configure Base URL

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

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

Configure Auth Token

Open httpClient/interceptors/request.ets:

export function requestInterceptor(options: RequestOptions): RequestOptions {
  const token = AppStorage.get<string>('token'); // ✏️ use your own token source
  if (token) {
    options.header = {
      ...options.header,
      'Authorization': `Bearer ${token}`,
    };
  }
  return options;
}

Open httpClient/interceptors/response.ets to handle auth errors:

export function responseInterceptor(response: HttpResponse): HttpResponse {
  if (response.responseCode === 401) {
    // ✏️ navigate to login page
    router.pushUrl({ url: 'pages/Login' });
  }
  return response;
}

Network Permissions

Add the following to entry/src/main/module.json5:

"requestPermissions": [
  { "name": "ohos.permission.INTERNET" }
]

Using the Generated APIs

import { ApiUser } from '../api/auto/demo/ApiUser';
import { UserPageQueryDto } from '../api/auto/demo/model';

async function loadUsers() {
  const params: UserPageQueryDto = { page: 1, limit: 10 };
  const users = await ApiUser.getUserList(params);
  console.info('users:', JSON.stringify(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.