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>
OpenAPI 文档自动生成功能
功能概述
服务启动时自动生成 OpenAPI 3.0 规范文档，确保文档始终与运行的服务保持同步。
使用方式
1. 自动生成（服务启动时）
当你启动 API 服务时，OpenAPI 文档会自动生成:
make run
# 或
go run cmd/api/main.go
文档将自动保存到项目根目录: ./openapi.yaml
2. 手动生成（独立工具）
如果需要离线生成文档（不启动服务），可以使用以下命令:
make docs
# 或
go run cmd/gendocs/main.go
文档将保存到: ./docs/admin-openapi.yaml
实现细节
核心文件
cmd/api/docs.go- 服务启动时的文档生成逻辑cmd/api/main.go- 在步骤 11 调用文档生成cmd/gendocs/main.go- 独立文档生成工具
生成流程
- 创建 OpenAPI 文档生成器
- 创建临时 Fiber App
- 注册所有路由（使用 nil 依赖）
- 保存文档到指定路径
- 生成失败时记录错误但不影响服务
错误处理
- 文档生成失败会记录到应用日志
- 服务启动不会因文档生成失败而中断
- 保证服务的可用性优先于文档生成
技术架构
避免循环依赖
文档生成逻辑放在各自的 cmd/ 包内，避免了 pkg/openapi → internal/routes 的循环依赖。
代码复用
两种生成方式（自动和手动）都使用相同的核心逻辑:
- 相同的路由注册机制
- 相同的文档生成器
- 仅输出路径不同
配置
.gitignore
自动生成的文档已添加到 .gitignore:
/openapi.yaml
这避免了将自动生成的文件提交到版本控制。
验证
编译测试
go build ./cmd/api
go build ./cmd/gendocs
功能测试
# 测试独立工具
make docs
# 检查生成的文档
ls -lh docs/admin-openapi.yaml