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 注释定义数据模型：

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

添加新的 API 文档

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

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

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

配置

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

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

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