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.4 KiB
1.4 KiB
Change: 服务启动时自动生成OpenAPI文档
Why
当前项目已经实现了OpenAPI文档生成功能，但需要手动执行 make docs 命令才能生成文档文件。这导致以下问题：
- 部署服务时容易忘记生成文档，导致文档与实际API不同步
- 开发过程中需要频繁手动执行命令来更新文档
- 无法保证文档与当前运行服务的API定义完全一致
通过在服务启动时自动生成OpenAPI文档，可以确保文档始终与当前服务保持同步，提升开发和部署体验。
What Changes
- 在
cmd/api/main.go的初始化流程中添加OpenAPI文档自动生成功能 - 将文档输出到项目根目录的固定位置（
./openapi.yaml） - 生成失败时记录错误日志但不影响服务启动
- 复用现有的文档生成逻辑（
pkg/openapi/和internal/routes/的Registry机制） - 移除或保留
cmd/gendocs/main.go作为备用工具（供离线生成文档使用）
Impact
Affected specs
- NEW:
openapi-generation- 新增OpenAPI文档自动生成规范
Affected code
cmd/api/main.go- 添加文档生成调用- 可能需要提取
cmd/gendocs/main.go中的生成逻辑为可复用函数 - 无需修改现有的
pkg/openapi/generator.go和internal/routes/registry.go
Breaking changes
无破坏性变更。现有的手动生成方式（make docs）仍然可以使用。