## Context
当前项目缺乏API文档，开发者需要通过阅读代码来理解API端点的使用方法。添加Swagger将提供交互式文档，改善开发者体验。

## Goals / Non-Goals

- Goals:
  - 为所有API端点提供交互式文档
  - 自动化API文档生成
  - 提供API使用示例
  - 支持API端点测试

- Non-Goals:
  - 完全重构API设计
  - 添加其他文档类型（如用户指南）

## Decisions

- Decision: 使用Swagger UI和swagger-jsdoc组合
  - Why: 提供易于集成的交互式API文档，可以从代码注释生成文档
  - Alternative: 手动编写OpenAPI规范，但维护成本高

- Decision: 将Swagger UI部署在 /api-docs 路径下
  - Why: 遵循行业惯例，避免与现有端点冲突
  - Alternative: /docs 或 /swagger，但 /api-docs 更明确

- Decision: 使用JSDoc注释样式添加API文档
  - Why: 最小化代码侵入，保持文档在源代码中
  - Alternative: 单独的规范文件，但不易维护

## Risks / Trade-offs

- 增加包大小 → 通过选择适当的Swagger库缓解
- 代码注释维护 → 与代码变更保持同步
- 安全考虑 → 确保生产环境中可以控制文档访问

## Migration Plan

1. 添加Swagger依赖到package.json
2. 配置Swagger设置和中间件
3. 为现有API端点添加文档注释
4. 验证所有端点的文档准确性