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>
84 lines
3.0 KiB
Markdown
84 lines
3.0 KiB
Markdown
# openapi-generation Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change auto-generate-openapi-docs. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: 服务启动时自动生成OpenAPI文档
|
||
|
||
系统启动时SHALL自动生成OpenAPI 3.0规范文档并保存到项目根目录。
|
||
|
||
#### Scenario: 服务正常启动时生成文档
|
||
|
||
- **WHEN** 服务启动流程执行到路由注册之后
|
||
- **THEN** 系统自动调用文档生成逻辑
|
||
- **AND** 在项目根目录生成 `openapi.yaml` 文件
|
||
- **AND** 文件内容包含所有已注册的API端点定义
|
||
|
||
#### Scenario: 文档生成失败时的优雅处理
|
||
|
||
- **WHEN** 文档生成过程中发生错误（如文件写入失败、权限问题）
|
||
- **THEN** 系统记录错误日志到应用日志
|
||
- **AND** 错误日志包含完整的错误信息和堆栈
|
||
- **AND** 服务启动流程继续执行，不因文档生成失败而中断
|
||
|
||
#### Scenario: 文档生成的时机控制
|
||
|
||
- **WHEN** 服务在任何环境下启动（开发、测试、生产）
|
||
- **THEN** 文档生成逻辑都会执行
|
||
- **AND** 无需额外的配置或启动参数
|
||
|
||
### Requirement: 文档输出路径规范
|
||
|
||
系统SHALL将生成的OpenAPI文档输出到固定的、可预测的位置。
|
||
|
||
#### Scenario: 文档保存到项目根目录
|
||
|
||
- **WHEN** 文档生成成功
|
||
- **THEN** 文件保存到项目根目录（相对于工作目录的 `./openapi.yaml`）
|
||
- **AND** 如果文件已存在则覆盖旧版本
|
||
- **AND** 文件权限设置为 0644（所有者可读写，其他用户只读）
|
||
|
||
#### Scenario: 确保输出目录存在
|
||
|
||
- **WHEN** 输出路径的父目录不存在
|
||
- **THEN** 系统自动创建必要的目录结构
|
||
- **AND** 目录权限设置为 0755
|
||
|
||
### Requirement: 复用现有生成逻辑
|
||
|
||
文档生成功能SHALL复用项目中已有的OpenAPI生成机制，避免代码重复。
|
||
|
||
#### Scenario: 调用现有的Registry机制
|
||
|
||
- **WHEN** 执行文档生成
|
||
- **THEN** 使用 `pkg/openapi.Generator` 创建文档生成器
|
||
- **AND** 调用 `internal/routes` 中的路由注册函数
|
||
- **AND** 传入非nil的Generator实例以激活文档收集逻辑
|
||
- **AND** 使用Generator的Save方法输出YAML文件
|
||
|
||
#### Scenario: 模拟路由注册但不启动服务
|
||
|
||
- **WHEN** 生成文档时调用路由注册函数
|
||
- **THEN** 创建临时的Fiber应用实例用于路由注册
|
||
- **AND** 传入nil的依赖项（因为不会执行实际的Handler逻辑）
|
||
- **AND** 注册完成后丢弃Fiber应用实例（不调用Listen）
|
||
|
||
### Requirement: 向后兼容独立生成工具
|
||
|
||
系统SHALL保留独立的文档生成工具，支持离线生成文档的用例。
|
||
|
||
#### Scenario: 通过make命令生成文档
|
||
|
||
- **WHEN** 用户执行 `make docs` 命令
|
||
- **THEN** 调用 `cmd/gendocs/main.go`
|
||
- **AND** 生成文档到指定位置（默认 `./docs/admin-openapi.yaml`）
|
||
- **AND** 生成过程独立于服务运行状态
|
||
|
||
#### Scenario: 独立工具与自动生成共享代码
|
||
|
||
- **WHEN** 独立工具和自动生成都需要执行文档生成
|
||
- **THEN** 两者调用相同的底层生成函数
|
||
- **AND** 通过参数区分输出路径
|
||
- **AND** 避免逻辑重复
|
||
|