使用Swaggo为net/http默认路由生成OpenAPI 3.1规范时遭遇Swagger UI版本验证错误

看起来你遇到的问题主要来自两个核心点——Swaggo没生成完整的API文档（paths字段为空），以及OpenAPI 3.1与Swagger UI的配置/兼容性不匹配。我来一步步帮你解决：

一、先理清问题根源 #

你生成的docs.go里paths是空的，这是最关键的问题之一——Swaggo完全依赖代码注释来识别你的HTTP接口，你没给Handler函数加规范注释，它就没法生成API路径信息，不完整的文档直接导致了Swagger UI解析失败。另外，虽然你指定了--v3.1参数，但注释规范和UI兼容性也拖了后腿。

二、分步解决指南 #

1. 给所有Handler函数补全Swaggo注释 #

这是生成完整文档的前提，每个HTTP接口都要加符合Swaggo规范的注释，比如：

新建风险的POST接口

// @Summary 创建新的风险记录
// @Description 提交风险信息，系统自动生成唯一ID并存储
// @Tags risks
// @Accept json
// @Produce json
// @Param risk body Risk true "风险实体，必须包含合法的state字段"
// @Success 200 {object} Risk "创建成功的风险记录，包含自动生成的ID"
// @Failure 400 {string} string "请求参数错误或state不合法"
// @Router /v1/risks [post]
func newRiskHandler(w http.ResponseWriter, r *http.Request) {
    // 原函数代码保持不变
}

列出所有风险的GET接口

// @Summary 获取所有风险记录
// @Description 查询系统中存储的所有风险条目
// @Tags risks
// @Produce json
// @Success 200 {array} Risk "所有风险记录的数组"
// @Router /v1/risks [get]
func listRisksHandler(w http.ResponseWriter, r *http.Request) {
    // 原函数代码保持不变
}

根据ID查询风险的GET接口

// @Summary 根据ID获取风险记录
// @Description 通过UUID格式的ID查询特定风险详情
// @Tags risks
// @Produce json
// @Param id path string true "风险记录的UUID"
// @Success 200 {object} Risk "匹配的风险记录"
// @Failure 400 {string} string "无效的UUID格式"
// @Router /v1/risks/{id} [get]
func getRiskHandler(w http.ResponseWriter, r *http.Request) {
    // 原函数代码保持不变
}

2. 修正主包的Swaggo注释规范 #

你的main函数上方的注释需要补充OpenAPI版本声明，同时修正服务器地址的写法：

// @title Risks API
// @version 1.0
// @description 风险记录管理后端API
// @server http://localhost:8080 本地开发服务器
// @openapi 3.1
package main

这里的@openapi 3.1会明确告诉Swaggo要生成OpenAPI 3.1规范的文档。

3. 正确重新生成文档（别手动改docs.go） #

手动修改docs.go没用，每次swag init都会覆盖它。先删除旧的docs目录，再用规范参数生成：

# 删除旧的生成文件
rm -rf docs
# 生成OpenAPI 3.1规范的文档
$HOME/go/bin/swag init --openapi 3.1

如果你的swag命令已经在系统PATH里，直接用swag init --openapi 3.1就行。

4. 解决Swagger UI兼容性问题 #

如果做完上面的步骤还是报错，大概率是http-swagger/v2对OpenAPI 3.1的支持不足，你可以二选一：

• 降级到OpenAPI 3.0：把注释里的@openapi 3.1改成@openapi 3.0，然后用swag init --openapi 3.0生成文档，Swagger UI对3.0的兼容性更稳定；
• 升级http-swagger包：运行go get -u github.com/swaggo/http-swagger/v2，用最新版本的http-swagger，它可能已经修复了3.1的兼容问题。

三、最后验证 #

重新生成文档后，启动你的服务：

go run main.go

再访问http://localhost:8080/swagger/index.html，应该就能看到完整的API文档，版本验证错误也会消失。

内容来源于stack exchange