React Integration Tutorial

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

Prerequisites

• Node.js ≥ 18, React ≥ 18
• 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 every time you run apisorcery generate. 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. window.location.href = '/login'
    }
    return Promise.reject(error);
  }
);

Using the Generated APIs

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

function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    ApiUser.getUserList({ page: 1, limit: 10 }).then(setUsers);
  }, []);

  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

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.