121 lines
2.7 KiB
Markdown
121 lines
2.7 KiB
Markdown
|
# 句容圈代理后台管理系统 API 文档
|
|||
|
|
|
|||
|
|
本目录包含了句容圈代理后台管理系统的完整 API 文档，使用 Swagger/OpenAPI 3.0 规范编写。
|
|||
|
|
|
|||
|
|
## 文档结构
|
|||
|
|
|
|||
|
|
### APIs 目录
|
|||
|
|
包含各个模块的 API 接口文档：
|
|||
|
|
|
|||
|
|
- `auth.js` - 认证管理接口（登录、获取用户信息、登出）
|
|||
|
|
- `agent.js` - 代理统计接口（统计数据、趋势分析、最新记录）
|
|||
|
|
- `captcha.js` - 验证码接口（生成验证码、验证验证码）
|
|||
|
|
- `commissions.js` - 佣金管理接口（佣金列表、详情、申请发放）
|
|||
|
|
- `transfers.js` - 转账管理接口（转账记录查询）
|
|||
|
|
- `upload.js` - 文件上传接口（各类文件上传、删除）
|
|||
|
|
- `users.js` - 用户管理接口（用户列表、详情、数据导出）
|
|||
|
|
|
|||
|
|
### Schemas 目录
|
|||
|
|
包含数据模型定义：
|
|||
|
|
|
|||
|
|
- `agent.js` - 代理数据模型
|
|||
|
|
- `user.js` - 用户数据模型
|
|||
|
|
- `commission.js` - 佣金记录数据模型
|
|||
|
|
- `transfer.js` - 转账记录数据模型
|
|||
|
|
- `security.js` - 安全认证配置
|
|||
|
|
|
|||
|
|
## 使用说明
|
|||
|
|
|
|||
|
|
### 1. 集成到项目
|
|||
|
|
|
|||
|
|
在你的 Express 应用中集成 Swagger UI：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
const swaggerJsdoc = require('swagger-jsdoc');
|
|||
|
|
const swaggerUi = require('swagger-ui-express');
|
|||
|
|
|
|||
|
|
const options = {
|
|||
|
|
definition: {
|
|||
|
|
openapi: '3.0.0',
|
|||
|
|
info: {
|
|||
|
|
title: '句容圈代理后台管理系统 API',
|
|||
|
|
version: '1.0.0',
|
|||
|
|
description: '句容圈代理后台管理系统的 RESTful API 文档',
|
|||
|
|
},
|
|||
|
|
servers: [
|
|||
|
|
{
|
|||
|
|
url: 'http://localhost:3000/api',
|
|||
|
|
description: '开发环境',
|
|||
|
|
},
|
|||
|
|
],
|
|||
|
|
},
|
|||
|
|
apis: [
|
|||
|
|
'./docs/apis/*.js',
|
|||
|
|
'./docs/schemas/*.js',
|
|||
|
|
],
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
const specs = swaggerJsdoc(options);
|
|||
|
|
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 访问文档
|
|||
|
|
|
|||
|
|
启动服务器后，访问 `http://localhost:3000/api-docs` 查看完整的 API 文档。
|
|||
|
|
|
|||
|
|
### 3. 认证说明
|
|||
|
|
|
|||
|
|
大部分 API 接口需要 JWT 认证，请在请求头中添加：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Authorization: Bearer <your-jwt-token>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 响应格式
|
|||
|
|
|
|||
|
|
所有 API 响应都遵循统一格式：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {},
|
|||
|
|
"message": "操作成功"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5. 分页格式
|
|||
|
|
|
|||
|
|
列表接口支持分页，响应格式：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"items": [],
|
|||
|
|
"total": 100,
|
|||
|
|
"page": 1,
|
|||
|
|
"limit": 10,
|
|||
|
|
"totalPages": 10
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 开发指南
|
|||
|
|
|
|||
|
|
### 添加新接口文档
|
|||
|
|
|
|||
|
|
1. 在 `apis/` 目录下创建或编辑对应的文件
|
|||
|
|
2. 使用 Swagger JSDoc 注释格式编写文档
|
|||
|
|
3. 如需要新的数据模型，在 `schemas/` 目录下添加
|
|||
|
|
|
|||
|
|
### 文档规范
|
|||
|
|
|
|||
|
|
- 使用中文描述
|
|||
|
|
- 包含完整的请求参数和响应示例
|
|||
|
|
- 标明必需参数和可选参数
|
|||
|
|
- 提供错误响应说明
|
|||
|
|
- 使用合适的 HTTP 状态码
|
|||
|
|
|
|||
|
|
## 更新日志
|
|||
|
|
|
|||
|
|
- v1.0.0 - 初始版本，包含所有核心 API 接口文档
|