huang
d9de704d73
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 49s
46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
# API 文档完整性规范
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### Requirement: OpenAPI 文档 100% 覆盖所有路由接口
|
||
|
||
系统的 OpenAPI 文档应包含所有已注册的 HTTP 路由接口，覆盖率达到 100%。
|
||
|
||
#### Scenario: 文档注册所有 Handler
|
||
|
||
- **WHEN** 系统启动或生成 OpenAPI 文档
|
||
- **THEN** `cmd/api/docs.go` 中的 `bootstrap.Handlers` 结构体包含全部 48 个 Handler（包括 Account、AdminOrder、AgentRecharge、Asset、AssetWallet 等）
|
||
- **THEN** 每个 Handler 对应一个已注册的路由组（如 `/api/admin/accounts` → `handlers.Account`）
|
||
- **THEN** 生成的 OpenAPI 文档包含这 48 个 Handler 对应的全部接口
|
||
|
||
#### Scenario: 新增 Handler 时同步文档生成器
|
||
|
||
- **WHEN** 开发者在 `internal/router/` 中新增一个 Handler 并注册到路由
|
||
- **THEN** 开发者必须同时在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中的 `bootstrap.Handlers` 结构体添加该 Handler 字段
|
||
- **THEN** 若遗漏，代码审查应拒绝合并（检查清单项：**新增 Handler 时是否同步更新 docs.go/gendocs/main.go**）
|
||
|
||
#### Scenario: OpenAPI 文档校验完整性
|
||
|
||
- **WHEN** 执行 `go run cmd/gendocs/main.go` 生成 OpenAPI 文档
|
||
- **THEN** 文档应包含所有已注册的接口路由
|
||
- **THEN** 无"缺失文档"的警告或错误信息
|
||
|
||
### Requirement: 文档生成器不遗漏 Handler
|
||
|
||
文档生成器的 `bootstrap.Handlers` 结构体应显式列出所有 Handler，避免新增后遗漏。
|
||
|
||
#### Scenario: 完整的 Handler 清单
|
||
|
||
- **WHEN** 审阅 `cmd/api/docs.go` 的 `bootstrap.Handlers` 结构体定义
|
||
- **THEN** 该结构体包含以下字段（至少 48 个，按模块分组）：
|
||
```go
|
||
Account *admin.AccountHandler
|
||
AdminOrder *admin.OrderHandler
|
||
AgentRecharge *agent.RechargeHandler
|
||
Asset *admin.AssetHandler
|
||
AssetWallet *admin.AssetWalletHandler
|
||
Authorization *admin.AuthorizationHandler
|
||
// ... 共 48 个
|
||
```
|
||
- **THEN** 注释中标注每个 Handler 对应的路由前缀和功能模块
|