v1.0

AngusTester 接口文档

下载 OpenAPI 文档

API 规范

AngusTester 基于RESTful 设计原则构建，并严格遵守OpenAPI 3.0规范格式。

1. 协议规范

强制使用 HTTPS
API 始终通过 HTTPS 提供服务，以确保数据传输安全。

注意：私有部署客户可能未配置安全证书，需要单独处理。
API 版本管理
版本号嵌入在 URL 路径中：
```
/api/v1/resource
/api/v2/resource
```

2. 资源命名规范

统一使用小写字母或小驼峰命名法 - 示例：
```
/user
/productCategories
/orderItems
```

3. HTTP 方法规范

方法	描述	成功码	示例
GET	获取资源	200	`GET /users`
POST	创建资源	201	`POST /users`
PUT	替换整个资源（不存在则创建）	200	`PUT /users/{id}`
PATCH	部分资源更新	200	`PATCH /users/{id}`
DELETE	删除资源	204	`DELETE /users/{id}`

特殊操作模式 - 使用动词/形容词进行精细操作：

PATCH /users/{id}/enabled   # 启用用户
POST /orders/{id}/cancel    # 取消订单

4. 安全认证

OAuth 2.0 认证 - 受保护资源需要认证头：
Authorization: Bearer <access_token>

5. 请求参数规范

请求头

Content-Type: application/json
Accept: application/json
Authorization: Bearer xxxxxxxxxxxx

查询参数

参数类型	格式示例	描述
分页	`?pageNo=2&pageSize=20`	页码和每页大小
排序	`?orderBy=createdDate&orderSort=DESC`	排序字段和方向
过滤	`?status=active&role=admin`	字段过滤器

请求体 (JSON)

{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "member",
  "preferences": {
    "notifications": true,
    "theme": "dark"
  }
}

6. 响应规范

状态码

代码	含义
200	成功 - 请求成功
201	已创建 - 资源创建成功
204	无内容 - 成功但无返回内容
400	错误请求 - 客户端错误
401	未授权 - 未认证
403	禁止访问 - 无权限
404	未找到 - 资源不存在
429	请求过多 - 超出频率限制
500	服务器内部错误 - 服务器故障

响应体结构

{
  "code": "S",
  "msg": "成功",
  "data": {
    "total": 42,
    "list": [
      {
        "id": "301222970049691648",
        "username": "U20250628001287",
        "email": "user@example.com"
      }
    ]
  },
  "datetime": "2025-06-15 14:49:56",
  "ext": {}
}

快速入门指南

1. 获取访问令牌

系统访问令牌

使用场景：系统间集成
获取流程:

登录 AngusGM 应用
导航到：系统 → 系统令牌
创建新令牌：
- 输入令牌名称
- 设置权限范围
- 配置过期时间
点击创建令牌生成新凭证

注意：系统令牌拥有完整的 API 权限，无数据限制。

用户访问令牌

使用场景：用户级 API 操作
获取流程:

登录 AngusGM 应用
访问：用户资料 → 访问令牌
创建新令牌：
- 验证用户密码
- 设置令牌名称
- 配置有效期
点击创建令牌生成凭证

注意：用户令牌继承用户的 API 权限和数据访问权限。

2. API 服务端点

部署类型	服务端点
云 SaaS 版	`https://bj-c1-prod-apis.xcan.cloud/tester`
私有部署	`http://TESTER_HOST:TESTER_PORT` (默认)
	或通过`TESTER_APIS_URL_PREFIX`配置

3. API 调用示例

curl -i 'https://bj-c1-prod-apis.xcan.cloud/tester/api/v1/task/search?pageNo=1&pageSize=10' \n  -H 'Accept: application/json'
  -H 'Authorization: Bearer 7RProMAjgCr40gMgrsnRROvMXHrXrDrzwqo7ti1V2ZXc6bjoWvVEOTkjbQnLAxMTi5fJrnET'

响应示例:

HTTP/1.1 200 OK
Date: Sun, 15 Jun 2025 06:49:56 GMT
Content-Type: application/json
XC-Request-Id: 34acb65c2c484188a2f9f3a3f4ca3d1f

{
  "code": "S",
  "msg": "成功",
  "data": {
    "total": "1",
    "list": [
      {
        "id": "301222970049691648",
        "code": "AT00000016",
        "name": "任务示例"
      }
    ]
  },
  "datetime": "2025-06-15 14:49:56"
}

联系方式

联系方式/technical_support@xcan.cloud

许可证

GPL-3.0

任务

协议测试

AngusTester 接口文档​