实现服务启动时自动生成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/gendocs/main.go

@@ -13,14 +13,24 @@ import (
 )
 
 func main() {
+	outputFile := "./docs/admin-openapi.yaml"
+	if err := generateAdminDocs(outputFile); err != nil {
+		log.Fatalf("生成 OpenAPI 文档失败: %v", err)
+	}
+
+	absPath, _ := filepath.Abs(outputFile)
+	log.Printf("成功在以下位置生成 OpenAPI 文档: %s", absPath)
+}
+
+// generateAdminDocs 生成 Admin API 的 OpenAPI 文档
+func generateAdminDocs(outputPath string) error {
 	// 1. 创建生成器
 	adminDoc := openapi.NewGenerator("Admin API", "1.0")
 
-	// 2. 模拟 Fiber App
+	// 2. 创建临时 Fiber App 用于路由注册
 	app := fiber.New()
 
-	// 3. 模拟 Handler
-	// 我们创建一个伪造的 handler。因为我们不执行请求，nil 依赖是可以的。
+	// 3. 创建 Handler（使用 nil 依赖,因为只需要路由结构）
 	accHandler := admin.NewAccountHandler(nil)
 	roleHandler := admin.NewRoleHandler(nil)
 	permHandler := admin.NewPermissionHandler(nil)
@@ -31,16 +41,14 @@ func main() {
 		Permission: permHandler,
 	}
 
-	// 4. 注册路由
+	// 4. 注册路由到文档生成器
 	adminGroup := app.Group("/api/admin")
 	routes.RegisterAdminRoutes(adminGroup, handlers, adminDoc, "/api/admin")
 
-	// 5. 保存规范
-	outputFile := "./docs/admin-openapi.yaml"
-	if err := adminDoc.Save(outputFile); err != nil {
-		log.Fatalf("保存规范失败: %v", err)
+	// 5. 保存规范到指定路径
+	if err := adminDoc.Save(outputPath); err != nil {
+		return err
 	}
 
-	absPath, _ := filepath.Abs(outputFile)
-	log.Printf("成功在以下位置生成 OpenAPI 规范: %s", absPath)
-}
+	return nil
+}