关于 Golang 框架 Goframe 中生成的SwaggerAPI文档 $ref异常内容

浏览：31次阅读

内容目录

最近在使用 gorframe 框架开发时，我定义了一个使用 Golang 泛型的 PageRes 类。然而，当尝试生成 Swagger 文档时，却遇到了持续报错的情况。通过查阅 Swagger 官方文档，我发现其 schema 值只支持 A-Z a-z 0-9 - . _ 范围内的字符。

经过排查 api.json 文件，我发现问题出在以下引用路径上：

#/components/schemas/protect-server.api.base.PageRes[protect-server/api/admin/app/v1.AppListItem]

对应的 schema key 是：

protect-server.api.base.PageRes[protect-server/api/admin/app/v1.AppListItem]

问题的根源在于这个路径中包含了 /、[ 和 ] 这三个 Swagger 不支持的特殊字符。这些字符是由于 Golang 泛型在类型名称中引入的。

以下是出错的 JSON 部分：

"protect-server.api.admin.app.v1.AppListRes": {
    "properties": {
      "code": {
        "format": "int",
        "type": "integer"
      },
      "message": {
        "format": "string",
        "type": "string"
      },
      "data": {"$ref": "#/components/schemas/protect-server.api.base.PageRes[protect-server/api/admin/app/v1.AppListItem]",
        "description": ""
      }
    },
    "type": "object"
  }

文件位置: net/goai/goai.go

为了解决这个问题，我对 schema 名称生成逻辑进行了修改，将不兼容的特殊字符替换为 Swagger 支持的字符：


func (oai *OpenApiV3) golangTypeToSchemaName(t reflect.Type) string {
    var (
        pkgPath    string
        schemaName = gstr.TrimLeft(t.String(), "*")
    )
    // Pointer type has no PkgPath.
    for t.Kind() == reflect.Pointer {t = t.Elem()
    }
    schemaName = gstr.Replace(schemaName, `/`, `.`)  // 增加
    if pkgPath = t.PkgPath(); pkgPath != "" && pkgPath != "." {
        if !oai.Config.IgnorePkgPath {schemaName = gstr.Replace(pkgPath, `/`, `.`) + gstr.SubStrFrom(schemaName, ".")
        }
    }
    schemaName = gstr.ReplaceByMap(schemaName, map[string]string{
        ` `: ``,
        `{`: ``,
        `}`: ``,
        `[`: `.`, // 增加
        `]`: `.`, // 增加
    })
    return schemaName
}

这段代码主要做了以下处理：