jurong_circle_black/docs/README.md

# API 文档结构说明

本项目已将 Swagger API 文档从路由文件中分离出来，采用模块化的文档管理方式。

## 文件夹结构

```
docs/
├── README.md          # 本说明文件
├── schemas/           # 数据模型定义
│   ├── product.js     # 商品相关数据模型
│   ├── order.js       # 订单相关数据模型
│   ├── user.js        # 用户相关数据模型
│   ├── cart.js        # 购物车相关数据模型
│   └── announcement.js # 通知公告相关数据模型
└── apis/              # API 接口定义
    ├── products.js    # 商品相关 API
    ├── orders.js      # 订单相关 API
    └── announcements.js # 通知公告相关 API
```

## 优势

1. **模块化管理**: 按功能模块分离文档，便于维护和查找
2. **代码分离**: 路由文件专注于业务逻辑，文档定义独立管理
3. **复用性**: Schema 定义可以在多个 API 中复用
4. **可维护性**: 文档修改不会影响业务代码，降低出错风险

## 使用方法

### 添加新的 Schema

在 `schemas/` 文件夹中创建新的 `.js` 文件，使用 `@swagger` 注释定义数据模型：

```javascript
/**
 * @swagger
 * components:
 *   schemas:
 *     YourModel:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *           description: ID
 */
```

### 添加新的 API 文档

在 `apis/` 文件夹中创建新的 `.js` 文件，使用 `@swagger` 注释定义 API 接口：

```javascript
/**
 * @swagger
 * tags:
 *   name: YourModule
 *   description: 模块描述
 */

/**
 * @swagger
 * /your-endpoint:
 *   get:
 *     summary: 接口描述
 *     tags: [YourModule]
 *     responses:
 *       200:
 *         description: 成功响应
 */
```

## 配置

Swagger 配置文件 `swagger.js` 已更新扫描路径：

```javascript
apis: ['./docs/schemas/*.js', './docs/apis/*.js', './routes/*.js', './admin/routes/*.js']
```

这样既保持了对现有路由文件中文档的兼容性，又支持新的模块化文档结构。