API 文档管理方案

现有基础设施

代表：swagger-jsdoc + swagger-ui-express（我们现在用的）

优点 成熟稳定，文档与代码紧密结合，社区资源多

缺点 需要手动编写大量注释，容易遗漏，重构时文档易过期

代表：swagger-autogen

优点 快速上手，路径自动发现

缺点 只能自动提取路径，参数和响应必须手动补充

代表：express-oas-generator

优点 真正零注解，跑过请求就有文档

缺点 冷启动文档不完整，推断 schema 可能不准，生产环境建议关闭

代表：tsoa、NestJS @nestjs/swagger

优点 类型安全，文档自动与代码同步

缺点 必须用 TypeScript + OOP 类语法，改造成本极高

代表：Stoplight Studio、Swagger Editor

优点 规范即文档，前后端可并行开发

缺点 需改变工作习惯，现有项目改造成本高

@scalar/express-api-reference - MIT 开源，2025-2026 年新星

• 暗色主题，现代 UI
• 内置 API Client，直接在页面测试端点
• 支持搜索、分组、代码示例自动生成
• 基于同一份 OpenAPI JSON，无需改注解

集成方式：替换 server.js 中的 GET /api-docs，保留 GET /api-docs.json

• 不一次性补完，按优先级分批
• 新 API 强制要求带 @swagger 注解
• 旧 API 按 P0 → P1 → P2 逐步补充

静态分析脚本，对比实际路由 vs OpenAPI 文档：

命令：npm run check:api-docs

现有 swagger-custom.html 中的快速登录功能（管理员/超级管理员一键登录）将通过注入脚本的方式迁移到 Scalar：

• 创建 scalar-login-inject.js，拦截 Scalar HTML 响应注入
• 保留右上角浮层按钮、localStorage 持久化、token 自动注入
• 调用 /api/auth/employee/login 获取 token 后设置到 Scalar 认证

appointments.js      cart_appointment.js   cash-drawer.js
centers.js           checkin.js            daily_availability.js
dev.js               discounts.js          employee_availability.js
employee_list.js     employees.js          gift-cards.js
guest-notes.js       guest-relationships.js guests.js
invoices.js          logs.js               loyalty.js
marketing.js         payment-docs.js       payment.js
permissions.js       promotion.js          receipts.js
schedule-templates.js schedules.js         services.js
settings.js          shopping_cart.js      stores.js
sync.js              terminals.js          user_feedback.js
user.js              voice-bot.js
admin/: audit, employees, gift-cards, permissions, roles, services

/**
 * @swagger
 * /api/{prefix}/{path}:
 *   {method}:
 *     summary: 一句话描述
 *     description: 详细说明（可选）
 *     tags: [{Tag Name}]
 *     security:                    # 需认证时
 *       - bearerAuth: []           # 员工 JWT
 *       - guestBearerAuth: []      # Guest JWT
 *     parameters:                  # GET / 路径参数
 *       - in: query|path
 *         name: xxx
 *         required: true|false
 *         schema:
 *           type: string|integer
 *     requestBody:                 # POST/PUT/PATCH
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [field1]
 *             properties:
 *               field1:
 *                 type: string
 *                 example: value
 *     responses:
 *       200: { description: 成功 }
 *       400: { description: 参数错误 }
 *       401: { description: 未认证 }
 *       403: { description: 权限不足 }
 *       404: { description: 不存在 }
 */