API文档生成与Apifox同步指南

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

1. 查看API文档

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

http://localhost:3000/api-docs

2. 手动导出并导入Apifox

2.1 导出Swagger文档

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

node export-swagger.js

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

2.2 手动导入Apifox

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

3. 自动同步到Apifox

3.1 安装Apifox CLI

npm install -g apifox-cli

3.2 登录Apifox CLI

apifox-cli login

3.3 配置项目ID

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

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

3.4 运行同步脚本

node apifox-sync.js

4. 为API添加Swagger注释

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

/**
 * @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. 定义数据模型

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

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

6. 自动化集成

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

如有任何问题，请参考Swagger官方文档和Apifox官方文档。

2.5 KiB Raw Blame History Unescape Escape