feiniao-site-node/docs

API文档生成说明

概述

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

使用方法

1. 生成API文档

# 方法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注释格式

基本结构

/**
 * @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. 重新运行生成脚本