如何让Swaggo识别map[string]json.RawMessage的两种合法结构体值？

我有一个API端点接受如下结构体类型：

type Foo struct {
    Id      *uuid.UUID
    Payload map[string]json.RawMessage
}

这样设计是因为我难以用其他方式在Go中表达多选项结构：键决定了对应值的结构。假设有如下两个结构体：

type Bla struct {
    MeaningOfLife int
}

和

type Fasel struct {
    Quest          string
    FavoriteColor  string
}

二者均为Payload对应的合法值，且由指定的键来区分。请问如何让Swaggo识别该map值对应的这两种具体合法类型？

方法1：通过注释明确键对应关系+示例 #

直接给Foo结构体的Payload字段添加Swaggo专属注释，明确标注允许的键和对应的数据结构，同时补充示例让文档更直观：

// Foo 接口请求结构体
// swagger:model
type Foo struct {
    Id      *uuid.UUID `json:"id"`
    // Payload 为动态映射结构，键名决定对应值的类型
    // 支持的键及对应类型：
    // - "bla": 对应 Bla 结构体
    // - "fasel": 对应 Fasel 结构体
    // swagger:allOf
    // example: {"bla": {"MeaningOfLife": 42}, "fasel": {"Quest": "寻找圣杯", "FavoriteColor": "蓝色"}}
    Payload map[string]json.RawMessage `json:"payload"`
}

// Bla Payload中"bla"键对应的数据结构
// swagger:model
type Bla struct {
    MeaningOfLife int `json:"meaningOfLife"`
}

// Fasel Payload中"fasel"键对应的数据结构
// swagger:model
type Fasel struct {
    Quest         string `json:"quest"`
    FavoriteColor string `json:"favoriteColor"`
}

Swaggo会解析这些注释，在生成的API文档中展示Payload的可选键和对应结构，示例也能帮助调用方理解实际格式。

方法2：用自定义Schema定义映射规则 #

通过schema注释直接为Payload定义JSON Schema，精准指定允许的键值对结构：

// Foo 接口请求结构体
// swagger:model
type Foo struct {
    Id      *uuid.UUID `json:"id"`
    // Payload 为固定键值对的动态映射，仅允许指定键及对应类型
    // swagger:strfmt json
    // schema: {"type": "object", "properties": {"bla": {"$ref": "#/definitions/Bla"}, "fasel": {"$ref": "#/definitions/Fasel"}}, "additionalProperties": false}
    Payload map[string]json.RawMessage `json:"payload"`
}

// Bla Payload中"bla"键对应的数据结构
// swagger:model
type Bla struct {
    MeaningOfLife int `json:"meaningOfLife"`
}

// Fasel Payload中"fasel"键对应的数据结构
// swagger:model
type Fasel struct {
    Quest         string `json:"quest"`
    FavoriteColor string `json:"favoriteColor"`
}

这种方式直接通过JSON Schema约束Payload的结构，Swaggo会基于此生成严格的API文档，甚至可以限制不允许出现额外的未知键。

方法3：调整结构使用oneOf（适合单一键场景） #

如果Payload每次只包含一个键（比如用键名标识类型），可以将Payload改为interface{}类型，结合oneOf注释声明允许的类型：

// Foo 接口请求结构体
// swagger:model
type Foo struct {
    Id      *uuid.UUID `json:"id"`
    // swagger:oneOf
    Payload interface{} `json:"payload"`
}

// Bla Payload可选类型之一
// swagger:model
type Bla struct {
    MeaningOfLife int `json:"meaningOfLife"`
}

// Fasel Payload可选类型之一
// swagger:model
type Fasel struct {
    Quest         string `json:"quest"`
    FavoriteColor string `json:"favoriteColor"`
}

需要注意这种方式需要自己处理序列化/反序列化的类型断言逻辑，但Swaggo会在文档中明确展示Payload的可选类型。

内容的提问来源于stack exchange，提问作者Benjamin Podszun