如何在Swagger 2.0/OpenAPI 3.x中指定API对象的JSON Raw Message？

阿华AIGC实验室

2026-5-14

处理Go中Json.RawMessage类型的Swagger 2.0文档方案

我之前给Go开发的REST API写Swagger 2.0文档时，也遇到过和你一样的困扰——Go里的Json.RawMessage在Swagger规范里确实没有直接对应的原生类型，试了字节字符串也觉得别扭。后来摸索出几个实用的方案，分享给你：

用object + additionalProperties表示任意JSON对象
因为Json.RawMessage本质就是一段未解析的JSON，多数场景下它最终会被解析成JSON对象。这种情况下，直接把字段定义为object类型，并开启additionalProperties: true，就能表示该字段可以是任意结构的JSON对象。示例YAML如下：
```
responses:
  200:
    description: 成功返回数据
    schema:
      type: object
      properties:
        user_id:
          type: integer
          format: int64
        custom_data:
          type: object
          additionalProperties: true
          description: 自定义动态数据（对应Go中的Json.RawMessage）
```
这个方案最直观，能让API调用者清楚知道该字段接受任意JSON对象结构。
用string + format: json表示原生JSON字符串
如果你的Json.RawMessage存储的是原始JSON字符串（毕竟底层是[]byte），可以把字段定义为string类型，同时指定format: json。虽然Swagger 2.0没有内置这个format，但它是行业通用的约定，大部分Swagger工具和文档阅读器都能识别，也能准确反映字段的本质。示例：
```
properties:
  raw_payload:
    type: string
    format: json
    description: 未解析的原始JSON数据（对应Go中的Json.RawMessage）
```

用oneOf枚举多种可能的结构
如果你能明确Json.RawMessage可能的几种结构（比如有时候是对象，有时候是字符串数组），可以用oneOf来列出所有可能的类型，让文档更精准。示例：

properties:
  flexible_content:
    oneOf:
      - type: object
        additionalProperties: true
      - type: array
        items:
          type: string
    description: 动态变化的内容，支持JSON对象或字符串数组（对应Go中的Json.RawMessage）

另外，如果你用的是go-swagger这类自动生成Swagger文档的工具，还可以通过结构体字段的注释直接指定Swagger规则，比如：

type APIResponse struct {
    UserID         int64             `json:"user_id" swagger:"type=integer,format=int64"`
    CustomData     json.RawMessage   `json:"custom_data" swagger:"type=object,additionalProperties=true"`
}

这样工具生成的Swagger文档会自动带上正确的字段定义，不用手动写YAML。

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