csxj2026/junhong_cmp_fiber

Files

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

2026-01-09 12:25:50 +08:00

2.1 KiB

Raw Blame History

OpenAPI 文档自动生成功能

功能概述

服务启动时自动生成 OpenAPI 3.0 规范文档，确保文档始终与运行的服务保持同步。

使用方式

1. 自动生成（服务启动时）

当你启动 API 服务时，OpenAPI 文档会自动生成:

make run
# 或
go run cmd/api/main.go

文档将自动保存到项目根目录: ./openapi.yaml

2. 手动生成（独立工具）

如果需要离线生成文档（不启动服务），可以使用以下命令:

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 - 独立文档生成工具

生成流程

创建 OpenAPI 文档生成器
创建临时 Fiber App
注册所有路由（使用 nil 依赖）
保存文档到指定路径
生成失败时记录错误但不影响服务

错误处理

文档生成失败会记录到应用日志
服务启动不会因文档生成失败而中断
保证服务的可用性优先于文档生成

技术架构

避免循环依赖

文档生成逻辑放在各自的 cmd/ 包内，避免了 pkg/openapi → internal/routes 的循环依赖。

代码复用

两种生成方式（自动和手动）都使用相同的核心逻辑:

相同的路由注册机制
相同的文档生成器
仅输出路径不同

配置

.gitignore

自动生成的文档已添加到 .gitignore:

/openapi.yaml

这避免了将自动生成的文件提交到版本控制。

验证

编译测试

go build ./cmd/api
go build ./cmd/gendocs

功能测试

# 测试独立工具
make docs

# 检查生成的文档
ls -lh docs/admin-openapi.yaml

2.1 KiB Raw Blame History Unescape Escape