dc940d2598
- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像 - 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档 - 添加Swagger API文档注释，完善接口描述和参数说明 - 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF - 添加输入验证和标准化响应格式 - 引入DOMPurify库对HTML内容进行安全过滤 - 更新环境变量配置，支持API密钥认证和CORS设置 - 优化上传逻辑，统一返回标准响应结构 - 添加构建脚本支持Docker镜像打包和推送
1.3 KiB
1.3 KiB
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
- 添加Swagger依赖到package.json
- 配置Swagger设置和中间件
- 为现有API端点添加文档注释
- 验证所有端点的文档准确性