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>
102 lines
2.1 KiB
Markdown
102 lines
2.1 KiB
Markdown
# 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) - 正式的功能规范
|