# API文档生成说明

## 概述

本项目使用JSDoc注释格式为API接口添加文档注释，并通过脚本自动生成OpenAPI格式的文档，可以直接导入到Apifox中进行API测试和文档管理。

## 使用方法

### 1. 生成API文档

```bash
# 方法1：使用npm脚本
npm run docs:generate

# 方法2：直接运行脚本
node scripts/generate-api-docs.js
```

### 2. 在Apifox中导入

1. 打开Apifox
2. 选择项目 → 导入
3. 选择"OpenAPI"格式
4. 导入生成的 `api-docs.yaml` 或 `api-docs.json` 文件
5. 完成导入后，所有接口注释都会显示在Apifox中

## JSDoc注释格式

### 基本结构

```javascript
/**
 * @api {method} path 接口名称
 * @apiName 接口名称
 * @apiGroup 分组名称
 * @apiVersion 版本号
 * 
 * @apiDescription 接口描述
 * 
 * @apiParam {Type} [paramName] 参数描述
 * @apiSuccess {Type} fieldName 返回字段描述
 * 
 * @apiSuccessExample {json} Success-Response:
 * HTTP/1.1 200 OK
 * {
 *   "status": true,
 *   "message": "成功",
 *   "data": {}
 * }
 */
```

### 参数类型

- `{String}` - 字符串类型
- `{Number}` - 数字类型
- `{Boolean}` - 布尔类型
- `{Object}` - 对象类型
- `{Array}` - 数组类型
- `{Date}` - 日期类型

### 参数说明

- `[paramName]` - 可选参数
- `paramName` - 必填参数
- `:id` - 路径参数

## 支持的API接口

目前已添加文档注释的接口：

1. **GET /admin/articles** - 查询文章列表
   - 支持分页：`currentPage`, `pageSize`
   - 支持筛选：`title`, `cropIds`, `categoryId`, `isRecommended`

2. **GET /admin/articles/:id** - 查询文章详情

3. **POST /admin/articles** - 创建文章
   - 必填字段：`title`, `content`
   - 可选字段：`subtitle`, `isRecommended`, `category`, `crop` 等

4. **PUT /admin/articles/:id** - 更新文章

5. **DELETE /admin/articles/:id** - 删除文章

## 文件说明

- `scripts/generate-api-docs.js` - API文档生成脚本
- `docs/api-docs.json` - 生成的JSON格式API文档
- `docs/api-docs.yaml` - 生成的YAML格式API文档

## 注意事项

1. 修改API接口后，需要重新运行生成脚本
2. JSDoc注释必须严格按照格式编写，否则可能解析失败
3. 生成的文档会覆盖之前的文件
4. 建议在每次API修改后都重新生成文档

## 扩展

如需为其他路由文件添加API文档，请：

1. 在相应的路由文件中添加JSDoc注释
2. 修改 `scripts/generate-api-docs.js` 中的文件路径
3. 重新运行生成脚本