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 接口文档 |