huang
6fc90abeb6
主要变更: 1. 新增 cmd/api/docs.go 实现文档自动生成逻辑 2. 修改 cmd/api/main.go 在服务启动时调用文档生成 3. 重构 cmd/gendocs/main.go 提取生成函数 4. 更新 .gitignore 忽略自动生成的 openapi.yaml 5. 新增 Makefile 支持 make docs 命令 6. OpenSpec 框架更新和变更归档 功能特性: - 服务启动时自动生成 OpenAPI 文档到项目根目录 - 保留独立的文档生成工具 (make docs) - 生成失败时记录错误但不影响服务启动 - 所有代码已通过 openspec validate --strict 验证 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1.3 KiB
1.3 KiB
Implementation Tasks
1. 重构文档生成逻辑
- 1.1 从
cmd/gendocs/main.go中提取文档生成逻辑（实际采用在各自包内实现的方案） - 1.2 创建文档生成函数，接受输出路径参数
- 1.3 确保函数返回错误而非panic（用于优雅处理失败情况）
2. 集成到服务启动流程
- 2.1 在
cmd/api/main.go的main()函数中添加文档生成调用 - 2.2 将生成调用放在路由注册之后（确保有完整的路由信息）
- 2.3 指定输出路径为
./openapi.yaml（项目根目录） - 2.4 生成失败时使用
appLogger.Error()记录错误但继续启动
3. 更新现有工具
- 3.1 保留
cmd/gendocs/main.go作为独立的文档生成工具 - 3.2 修改
cmd/gendocs/main.go使用提取的生成逻辑 - 3.3 Makefile 中的
docs目标保持不变（如存在）
4. 文档和测试
- 4.1 在
.gitignore中添加/openapi.yaml（避免提交自动生成的文件） - 4.2 手动测试文档生成工具，验证文档正确生成
- 4.3 编译测试确保代码无错误
- 4.4 README.md 更新将在后续完成
5. 清理和验证
- 5.1 确保代码符合项目规范（gofmt、go vet）
- 5.2 确保所有函数都有中文文档注释
- 5.3 运行
openspec validate auto-generate-openapi-docs --strict