实现服务启动时自动生成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>

openspec/changes/archive/2026-01-09-auto-generate-openapi-docs/README.md

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