# API文档生成与Apifox同步指南

本项目已集成Swagger用于API文档生成，并提供了与Apifox同步的工具脚本。

## 1. 查看API文档

启动服务器后，可以通过以下URL访问Swagger UI界面查看API文档：

```
http://localhost:3000/api-docs
```

## 2. 手动导出并导入Apifox

### 2.1 导出Swagger文档

运行以下命令导出Swagger文档：

```bash
node export-swagger.js
```

这将在`api-docs`目录下生成`swagger.json`文件。

### 2.2 手动导入Apifox

1. 打开Apifox应用
2. 选择您的项目
3. 点击"导入"按钮
4. 选择"导入OpenAPI(Swagger)"
5. 选择刚才导出的swagger.json文件
6. 按照Apifox的导入向导完成导入

## 3. 自动同步到Apifox

### 3.1 安装Apifox CLI

```bash
npm install -g apifox-cli
```

### 3.2 登录Apifox CLI

```bash
apifox-cli login
```

### 3.3 配置项目ID

编辑`apifox-sync.js`文件，将`YOUR_APIFOX_PROJECT_ID`替换为您的Apifox项目ID。

> 获取项目ID：在Apifox网页版中打开项目，URL中包含项目ID

### 3.4 运行同步脚本

```bash
node apifox-sync.js
```

## 4. 为API添加Swagger注释

为了使API文档保持最新，在添加新的API接口时，请按照以下格式添加Swagger注释：

```javascript
/**
 * @swagger
 * /api/resource:
 *   get:
 *     summary: 接口描述
 *     tags: [资源分类]
 *     parameters:
 *       - name: param
 *         in: query
 *         description: 参数描述
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: 成功响应
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: object
 */
router.get('/resource', (req, res) => {
  // 实现代码
});
```

## 5. 定义数据模型

在路由文件顶部定义数据模型，例如：

```javascript
/**
 * @swagger
 * components:
 *   schemas:
 *     ModelName:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *         name:
 *           type: string
 *       required:
 *         - name
 */
```

## 6. 自动化集成

可以将API文档生成和同步集成到CI/CD流程中，在每次部署前自动更新API文档。

---

如有任何问题，请参考[Swagger官方文档](https://swagger.io/docs/)和[Apifox官方文档](https://www.apifox.cn/help/)。