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