实现服务启动时自动生成OpenAPI文档

主要变更:
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>

cmd/api/docs.go

@@ -0,0 +1,46 @@
+package main
+
+import (
+	"github.com/gofiber/fiber/v2"
+	"go.uber.org/zap"
+
+	"github.com/break/junhong_cmp_fiber/internal/bootstrap"
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/routes"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// generateOpenAPIDocs 生成 OpenAPI 文档
+// outputPath: 文档输出路径
+// logger: 日志记录器
+// 生成失败时记录错误但不影响程序继续运行
+func generateOpenAPIDocs(outputPath string, logger *zap.Logger) {
+	// 1. 创建生成器
+	adminDoc := openapi.NewGenerator("Admin API", "1.0")
+
+	// 2. 创建临时 Fiber App 用于路由注册
+	app := fiber.New()
+
+	// 3. 创建 Handler（使用 nil 依赖,因为只需要路由结构）
+	accHandler := admin.NewAccountHandler(nil)
+	roleHandler := admin.NewRoleHandler(nil)
+	permHandler := admin.NewPermissionHandler(nil)
+
+	handlers := &bootstrap.Handlers{
+		Account:    accHandler,
+		Role:       roleHandler,
+		Permission: permHandler,
+	}
+
+	// 4. 注册路由到文档生成器
+	adminGroup := app.Group("/api/admin")
+	routes.RegisterAdminRoutes(adminGroup, handlers, adminDoc, "/api/admin")
+
+	// 5. 保存规范到指定路径
+	if err := adminDoc.Save(outputPath); err != nil {
+		logger.Error("生成 OpenAPI 文档失败", zap.String("path", outputPath), zap.Error(err))
+		return
+	}
+
+	logger.Info("OpenAPI 文档生成成功", zap.String("path", outputPath))
+}

cmd/api/main.go

@@ -71,7 +71,10 @@ func main() {
 	// 10. 注册路由
 	initRoutes(app, cfg, handlers, queueClient, db, redisClient, appLogger)
 
-	// 11. 启动服务器
+	// 11. 生成 OpenAPI 文档
+	generateOpenAPIDocs("./openapi.yaml", appLogger)
+
+	// 12. 启动服务器
 	startServer(app, cfg, appLogger, cancelWatch)
 }