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>
32 lines
1.4 KiB
Markdown
32 lines
1.4 KiB
Markdown
# 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`）仍然可以使用。
|