Go Echo框架导入外部包结构体致Swagger示例值失效求助

当使用Go的Echo框架搭建服务并集成Swagger时，若结构体字段引用了其他包的结构体，会出现Swagger示例值仅显示{}的情况，而同包结构体的示例值能正常生成。

问题复现 #

同包结构体场景（示例值正常显示）：

type Test struct {
    TestField string `json:"test_field" example:"testfield"`
}

type MaintenanceConfigPage struct {
    ConfigFile  string `json:"config_file" example:"configfile"`
    Test        Test   `json:"test"`
}

// maintenance godoc
// @Accept json
// @Produce json
// @Param data body MaintenanceConfigPage true "Config configuration"
// @Success 200 {object} string
// @Failure 400 {object} string
// @Router /maintenance [post]
func maintenanceSetupPost(echo_context echo.Context) error {
    return echo_context.JSON(http.StatusOK, "test")
}

此时Swagger示例值：

{
"config_file": "configfile",
"test": {
"test_field": "testfield"
}
}

跨包结构体场景（示例值异常）：

type MaintenanceConfigPage struct {
    ConfigFile  string                      `json:"config_file" example:"configfile"`
    Test        anotherPackage.Test         `json:"test"`
}

此时Swagger中test字段示例值仅显示：

{}

解决方案 #

方案1：启用Swag的依赖解析

Swag工具默认仅扫描当前包的结构体，添加--parseDependency参数可以让它解析依赖包的结构体字段标签，从而获取跨包结构体的示例值。

执行初始化命令：

swag init --parseDependency

注意：需确保跨包结构体是导出状态（首字母大写），否则Swag无法读取其字段信息。

方案2：本地字段直接指定示例JSON

如果无法修改跨包结构体，或不想依赖依赖解析，可以在本地字段的example标签中直接写入跨包结构体的示例JSON：

type MaintenanceConfigPage struct {
    ConfigFile  string                      `json:"config_file" example:"configfile"`
    Test        anotherPackage.Test         `json:"test" example:"{\"test_field\":\"testfield\"}"`
}

这种方式会强制Swagger使用指定的JSON作为该字段的示例值，不受跨包限制。

方案3：优化跨包结构体的Swagger识别

如果有权限修改跨包结构体，确保结构体本身导出且字段标签正确，同时可添加Swagger注释提升识别率：

// anotherPackage/structs.go
// Test 测试结构体
// @Description 用于传递测试字段的结构体
type Test struct {
    TestField string `json:"test_field" example:"testfield"`
}

之后执行swag init --parseDependency即可正常获取示例值。

内容的提问来源于stack exchange，提问作者Manish Garotki