174 lines
4.0 KiB
Markdown
174 lines
4.0 KiB
Markdown
|
# ToolsShow API Reference
|
||
|
|
|
||
|
|
Base URL: `/api/v1`
|
||
|
|
|
||
|
|
All JSON responses (except binary download stream) use the wrapper:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"code": 0,
|
||
|
|
"message": "ok",
|
||
|
|
"data": {},
|
||
|
|
"traceId": "uuid",
|
||
|
|
"timestamp": "2026-03-26T10:10:00.000Z"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Public APIs
|
||
|
|
|
||
|
|
| Method | Path | Description |
|
||
|
|
|---|---|---|
|
||
|
|
| GET | `/health` | Liveness/readiness check |
|
||
|
|
| GET | `/tools` | Query tools list (query/category/sort/page/pageSize) |
|
||
|
|
| GET | `/tools/:id` | Tool detail |
|
||
|
|
| POST | `/tools/:id/launch` | Unified launch (web/download) |
|
||
|
|
| GET | `/downloads/:ticket` | Consume ticket and stream artifact |
|
||
|
|
| GET | `/categories` | Category list with tool count |
|
||
|
|
| GET | `/keywords/hot` | Hot keyword list |
|
||
|
|
| GET | `/overview` | KPI overview |
|
||
|
|
|
||
|
|
### `GET /tools` query params
|
||
|
|
|
||
|
|
| Param | Type | Required | Default |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `query` | string | No | - |
|
||
|
|
| `category` | string | No | `all` |
|
||
|
|
| `sortBy` | `popular \| latest \| rating \| name` | No | `latest` |
|
||
|
|
| `page` | number | No | `1` |
|
||
|
|
| `pageSize` | number (1-50) | No | `6` |
|
||
|
|
|
||
|
|
### `POST /tools/:id/launch` body
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"channel": "official",
|
||
|
|
"clientVersion": "web-1.0.0"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Web mode response:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"mode": "web",
|
||
|
|
"actionUrl": "https://example.com",
|
||
|
|
"openIn": "new_tab"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Download mode response:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"mode": "download",
|
||
|
|
"ticket": "dl_tk_xxx",
|
||
|
|
"expiresInSec": 120,
|
||
|
|
"actionUrl": "/api/v1/downloads/dl_tk_xxx"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Admin Auth APIs
|
||
|
|
|
||
|
|
Auth header for protected admin APIs:
|
||
|
|
|
||
|
|
```text
|
||
|
|
Authorization: Bearer <accessToken>
|
||
|
|
```
|
||
|
|
|
||
|
|
| Method | Path | Auth | Description |
|
||
|
|
|---|---|---|---|
|
||
|
|
| POST | `/admin/auth/login` | No | Admin login |
|
||
|
|
| POST | `/admin/auth/refresh` | No | Refresh tokens |
|
||
|
|
| POST | `/admin/auth/logout` | Yes | Admin logout |
|
||
|
|
| GET | `/admin/auth/me` | Yes | Current admin profile |
|
||
|
|
|
||
|
|
Default seeded admin account:
|
||
|
|
|
||
|
|
```text
|
||
|
|
username: admin
|
||
|
|
password: admin123456
|
||
|
|
```
|
||
|
|
|
||
|
|
## Admin Tool APIs
|
||
|
|
|
||
|
|
| Method | Path | Description |
|
||
|
|
|---|---|---|
|
||
|
|
| GET | `/admin/tools` | Query tools |
|
||
|
|
| POST | `/admin/tools` | Create tool |
|
||
|
|
| GET | `/admin/tools/:id` | Tool detail |
|
||
|
|
| PATCH | `/admin/tools/:id` | Update tool |
|
||
|
|
| PATCH | `/admin/tools/:id/status` | Update tool status |
|
||
|
|
| PATCH | `/admin/tools/:id/access-mode` | Switch access mode |
|
||
|
|
| DELETE | `/admin/tools/:id` | Soft delete tool |
|
||
|
|
|
||
|
|
### Create/Update tool payload core fields
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"name": "Tool Name",
|
||
|
|
"categoryId": "cat_dev",
|
||
|
|
"description": "Tool description",
|
||
|
|
"rating": 4.5,
|
||
|
|
"tags": ["tag_hot", "tag_free"],
|
||
|
|
"features": ["Feature A", "Feature B"],
|
||
|
|
"accessMode": "web",
|
||
|
|
"openUrl": "https://example.com",
|
||
|
|
"openInNewTab": true,
|
||
|
|
"status": "draft"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Admin Artifact APIs
|
||
|
|
|
||
|
|
| Method | Path | Description |
|
||
|
|
|---|---|---|
|
||
|
|
| POST | `/admin/tools/:id/artifacts` | Upload artifact (`multipart/form-data`) |
|
||
|
|
| GET | `/admin/tools/:id/artifacts` | List artifacts |
|
||
|
|
| PATCH | `/admin/tools/:id/artifacts/:artifactId/latest` | Set latest artifact |
|
||
|
|
| PATCH | `/admin/tools/:id/artifacts/:artifactId/status` | Update artifact status |
|
||
|
|
| DELETE | `/admin/tools/:id/artifacts/:artifactId` | Soft delete artifact metadata |
|
||
|
|
|
||
|
|
### Upload form fields
|
||
|
|
|
||
|
|
| Field | Type | Required |
|
||
|
|
|---|---|---|
|
||
|
|
| `file` | binary | Yes |
|
||
|
|
| `version` | string | Yes |
|
||
|
|
| `releaseNotes` | string | No |
|
||
|
|
| `isLatest` | boolean | No (default `true`) |
|
||
|
|
|
||
|
|
## Admin Audit APIs
|
||
|
|
|
||
|
|
| Method | Path | Description |
|
||
|
|
|---|---|---|
|
||
|
|
| GET | `/admin/audit-logs` | Query admin audit logs |
|
||
|
|
|
||
|
|
Query params:
|
||
|
|
|
||
|
|
| Param | Type | Required |
|
||
|
|
|---|---|---|
|
||
|
|
| `action` | string | No |
|
||
|
|
| `resourceType` | string | No |
|
||
|
|
| `adminUserId` | string | No |
|
||
|
|
| `page` | number | No |
|
||
|
|
| `pageSize` | number | No |
|
||
|
|
|
||
|
|
## Error Codes
|
||
|
|
|
||
|
|
| Code | Meaning |
|
||
|
|
|---|---|
|
||
|
|
| `1001` | validation failed |
|
||
|
|
| `1002` | unauthorized |
|
||
|
|
| `1003` | forbidden |
|
||
|
|
| `1004` | resource not found |
|
||
|
|
| `1005` | conflict |
|
||
|
|
| `1010` | invalid credentials |
|
||
|
|
| `1011` | token invalid/expired |
|
||
|
|
| `1201` | GitLab upload failed |
|
||
|
|
| `1202` | GitLab download failed |
|
||
|
|
| `1203` | artifact not available |
|
||
|
|
| `1204` | download ticket invalid/expired |
|
||
|
|
| `1210` | tool access mode mismatch |
|
||
|
|
| `1211` | web open URL not configured |
|
||
|
|
| `1500` | internal server error |
|