Commit/update swagger generator

[winfredLIN]

关联的 issue

#581

描述你的变更

1. 升级swagger生成器到v0.33.1对应go大版本：Go: 1.24
2. 更新swagger定义中旧版本的enum定义
3. 更新swagger文档
4. 补充了检查swagger生成器版本和当前golang版本是否匹配（swagger生成器依赖golang对代码进行解析）的方法，并且默认在生成swagger之前进行检查，以便发现不匹配的问题，减少后续维护成本。

如果不匹配，会输出：

root@localhost ~/SQLE/ce/dms main* ❯ make check_swag_version                                                                                      07:50:59 AM
Project go.mod Version: 1.24.0
Swagger Version: v0.30.4 (Expected Go: 1.19)
System Go Version: 1.24.4
Warning: Current Swagger generator (v0.30.4, Go 1.19) does not match project's go.mod (1.24.0).
Please update the Swagger generator to match the project Go version.

如果匹配，会输出：

root@localhost ~/SQLE/ce/dms main* ❯ make check_swag_version                                                                                      07:51:16 AM
Project go.mod Version: 1.24.0
Swagger Version: v0.33.1 (Expected Go: 1.24.0)
System Go Version: 1.24.4

确认项（pr提交后操作）

Tip

请在指定复审人之前，确认并完成以下事项，完成后✅

---

• 我已完成自测
• 我已记录完整日志方便进行诊断
• 我已在关联的issue里补充了实现方案
• 我已在关联的issue里补充了测试影响面
• 我已确认了变更的兼容性，如果不兼容则在issue里标记 not_compatible
• 我已确认了是否要更新文档，如果要更新则在issue里标记 need_update_doc

---

[github-actions]

PR Reviewer Guide 🔍

🎫 Ticket compliance analysis 🔶 581 - Partially compliant Compliant requirements: 升级swagger生成器至v0.33.1并确保与Go 1.24匹配 更新swagger文档定义，包括enum和DateTime等字段调整 新增检查swagger生成器版本与项目Go版本匹配的逻辑 Non-compliant requirements: 无 Requires further human verification: 无

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review 枚举格式更新 新增的枚举注释采用了JSON数组语法，请确认在整个项目中枚举的定义格式保持统一和正确。 // enum: ["save_audit_plan","create_workflow","create_export_task"] Makefile验证逻辑 新增的check_swag_version目标逻辑较复杂，建议对其进行严格测试并确保未来的维护不会引入版本对比问题。 gen_swag: check_swag_version ./internal/apiserver/cmd/swag/swagger_${HOST_OS}_${HOST_ARCH} generate spec -m -w ./internal/apiserver/cmd/server/ -o ./api/swagger.yaml ./internal/apiserver/cmd/swag/swagger_${HOST_OS}_${HOST_ARCH} generate spec -i ./api/swagger.yaml -o ./api/swagger.json check_swag_version: @SWAG_BIN=./internal/apiserver/cmd/swag/swagger_${HOST_OS}_${HOST_ARCH}; \ SWAG_VER=$$($$SWAG_BIN version | grep 'version:' | awk '{print $$2}'); \ MATCHING_GO_VER="unknown"; \ MAPPINGS="v0.33.1:1.24.0 v0.31.0:1.22 v0.30.4:1.19 v0.29.0:1.18"; \ for m in $$MAPPINGS; do \ v=$${m%%:*}; g=$${m#*:}; \ if [ "$$v" = "$$SWAG_VER" ]; then MATCHING_GO_VER="$$g"; break; fi; \ done; \ if [ "$$MATCHING_GO_VER" = "unknown" ]; then \ echo "Fetching Go version for $$SWAG_VER from GitHub..."; \ MATCHING_GO_VER=$$(curl -sL --connect-timeout 2 https://raw.githubusercontent.com/go-swagger/go-swagger/$$SWAG_VER/go.mod | grep "^go " | awk '{print $$2}' 2>/dev/null); \ if [ -z "$$MATCHING_GO_VER" ]; then MATCHING_GO_VER="unknown"; fi; \ fi; \ PROJECT_GO_VER=$$(grep "^go " go.mod | awk '{print $$2}'); \ SYSTEM_GO_VER=$$(go version | awk '{print $$3}' | sed 's/go//'); \ echo "Project go.mod Version: $$PROJECT_GO_VER"; \ echo "Swagger Version: $$SWAG_VER (Expected Go: $$MATCHING_GO_VER)"; \ echo "System Go Version: $$SYSTEM_GO_VER"; \ if [ "$$MATCHING_GO_VER" != "unknown" ]; then \ PROJECT_GO_MAJOR=$$(echo $$PROJECT_GO_VER | cut -d. -f1,2); \ MATCH_GO_VER_MAJOR=$$(echo $$MATCHING_GO_VER | cut -d. -f1,2); \ SYSTEM_GO_MAJOR=$$(echo $$SYSTEM_GO_VER | cut -d. -f1,2); \ if [ "$$PROJECT_GO_MAJOR" != "$$MATCH_GO_VER_MAJOR" ]; then \ echo "Warning: Current Swagger generator ($$SWAG_VER, Go $$MATCHING_GO_VER) does not match project's go.mod ($$PROJECT_GO_VER)."; \ echo "Please update the Swagger generator to match the project Go version."; \ fi; \ if [ "$$PROJECT_GO_MAJOR" != "$$SYSTEM_GO_MAJOR" ]; then \ echo "Warning: Your system Go version ($$SYSTEM_GO_VER) does not match project's go.mod ($$PROJECT_GO_VER)."; \ fi; \ fi Swagger定义 新增的DateTime schema定义需要和项目中其他日期时间格式保持一致，建议核实格式和描述是否符合预期。 DateTime: description: |- DateTime is a time but it serializes to ISO8601 format with millis It knows how to read 3 different variations of a RFC3339 date time. Most APIs we encounter want either millisecond or second precision times. This just tries to make it worry-free. format: date-time type: string x-go-package: github.com/go-openapi/strfmt

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	强制版本匹配检查 建议将 Swagger 生成器版本不匹配的警告升级为构建错误（即直接退出构建），以防止由于版本不一致引发后续问题。这样可以确保项目使用与 go.mod 文件相匹配的 Swagger 生成器版本，更有利于长期项目稳定性。 Makefile [199-229] check_swag_version: @SWAG_BIN=./internal/apiserver/cmd/swag/swagger_${HOST_OS}_${HOST_ARCH}; \ SWAG_VER=$$($$SWAG_BIN version | grep 'version:' | awk '{print $$2}'); \ MATCHING_GO_VER="unknown"; \ MAPPINGS="v0.33.1:1.24.0 v0.31.0:1.22 v0.30.4:1.19 v0.29.0:1.18"; \ for m in $$MAPPINGS; do \ v=$${m%%:*}; g=$${m#*:}; \ if [ "$$v" = "$$SWAG_VER" ]; then MATCHING_GO_VER="$$g"; break; fi; \ done; \ if [ "$$MATCHING_GO_VER" = "unknown" ]; then \ echo "Fetching Go version for $$SWAG_VER from GitHub..."; \ MATCHING_GO_VER=$$(curl -sL --connect-timeout 2 https://raw.githubusercontent.com/go-swagger/go-swagger/$$SWAG_VER/go.mod | grep "^go " | awk '{print $$2}' 2>/dev/null); \ if [ -z "$$MATCHING_GO_VER" ]; then MATCHING_GO_VER="unknown"; fi; \ fi; \ PROJECT_GO_VER=$$(grep "^go " go.mod | awk '{print $$2}'); \ SYSTEM_GO_VER=$$(go version | awk '{print $$3}' | sed 's/go//'); \ echo "Project go.mod Version: $$PROJECT_GO_VER"; \ echo "Swagger Version: $$SWAG_VER (Expected Go: $$MATCHING_GO_VER)"; \ echo "System Go Version: $$SYSTEM_GO_VER"; \ if [ "$$MATCHING_GO_VER" != "unknown" ]; then \ PROJECT_GO_MAJOR=$$(echo $$PROJECT_GO_VER | cut -d. -f1,2); \ MATCH_GO_VER_MAJOR=$$(echo $$MATCHING_GO_VER | cut -d. -f1,2); \ SYSTEM_GO_MAJOR=$$(echo $$SYSTEM_GO_VER | cut -d. -f1,2); \ if [ "$$PROJECT_GO_MAJOR" != "$$MATCH_GO_VER_MAJOR" ]; then \ - echo "Warning: Current Swagger generator ($$SWAG_VER, Go $$MATCHING_GO_VER) does not match project's go.mod ($$PROJECT_GO_VER)."; \ - echo "Please update the Swagger generator to match the project Go version."; \ + echo "Error: Swagger generator version ($$SWAG_VER, Go $$MATCHING_GO_VER) does not match project's go.mod ($$PROJECT_GO_VER)."; \ + exit 1; \ fi; \ if [ "$$PROJECT_GO_MAJOR" != "$$SYSTEM_GO_MAJOR" ]; then \ - echo "Warning: Your system Go version ($$SYSTEM_GO_VER) does not match project's go.mod ($$PROJECT_GO_VER)."; \ + echo "Error: System Go version ($$SYSTEM_GO_VER) does not match project's go.mod ($$PROJECT_GO_VER)."; \ + exit 1; \ fi; \ fi Suggestion importance[1-10]: 8 __ Why: Upgrading the warning messages to error out with exit codes in the check_swag_version rule ensures stricter version matching, improving build stability when the Swagger generator version does not match the project’s Go version.	Medium
General	确认枚举格式更新 当前对枚举格式的更新符合 Swagger 规范，没有发现潜在的严重问题。请确保文档和代码逻辑同步更新。 api/dms/service/v1/db_service.go [267] +// enum: ["save_audit_plan","create_workflow","create_export_task"] - Suggestion importance[1-10]: 3 __ Why: The suggestion verifies that the updated enum comment using Swagger compliant JSON array syntax is correct, and it does not introduce any functional change.	Low