SocketIO /get路由Swagger UI示例值为空，求规范配置方案

问题背景 #

需要为SocketIO的/get路由编写Swagger文档，请求格式为["get",{"id":"66ab972245a202801187dce8"}]，响应格式为["answer",{"id":"66ab972245a202801187dce8", ...}]。现有配置下Swagger UI的示例值字段为空，需调整配置让示例正常显示且格式清晰。

修正后的完整Swagger配置 #

Paths 配置 #

"/get": {
  "post": {
    "tags": ["widgets"],
    "summary": "通过SocketIO获取Widget详情",
    "operationId": "getWidget",
    "servers": [
      {
        "url": "ws://localhost:8080"
      }
    ],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SocketWidgetRequest"
          },
          "example": ["get", {"id": "66ab972245a202801187dce8"}]
        }
      }
    },
    "responses": {
      "200": {
        "description": "Widget详情数据",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SocketWidgetResponse"
            },
            "example": ["answer", {
              "id": "66ab972245a202801187dce8",
              "title": {"en": "Sample Widget", "zh": "示例组件"},
              "folderId": "66ab970045a202801187dce6",
              "icon": "📊",
              "data": {"value": 123, "type": "metric"},
              "type": "chart"
            }]
          }
        }
      }
    }
  }
}

Components Schemas 配置 #

"components": {
  "schemas": {
    "SocketWidgetRequest": {
      "type": "array",
      "prefixItems": [
        {
          "type": "string",
          "enum": ["get"],
          "example": "get"
        },
        {
          "$ref": "#/components/schemas/Id"
        }
      ],
      "minItems": 2,
      "maxItems": 2,
      "example": ["get", {"id": "66ab972245a202801187dce8"}]
    },
    "SocketWidgetResponse": {
      "type": "array",
      "prefixItems": [
        {
          "type": "string",
          "enum": ["answer"],
          "example": "answer"
        },
        {
          "$ref": "#/components/schemas/GetWidgetResponse"
        }
      ],
      "minItems": 2,
      "maxItems": 2,
      "example": ["answer", {
        "id": "66ab972245a202801187dce8",
        "title": {"en": "Sample Widget", "zh": "示例组件"},
        "folderId": "66ab970045a202801187dce6",
        "icon": "📊",
        "data": {"value": 123, "type": "metric"},
        "type": "chart"
      }]
    },
    "Id": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "nullable": true,
          "example": "66ab972245a202801187dce8"
        }
      },
      "required": ["id"]
    },
    "GetWidgetResponse": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "66ab972245a202801187dce8"
        },
        "title": {
          "type": "object",
          "example": {"en": "Sample Widget", "zh": "示例组件"}
        },
        "folderId": {
          "type": "string",
          "nullable": true,
          "example": "66ab970045a202801187dce6"
        },
        "icon": {
          "type": "string",
          "nullable": true,
          "example": "📊"
        },
        "data": {
          "type": "object",
          "example": {"value": 123, "type": "metric"}
        },
        "type": {
          "type": "string",
          "example": "chart"
        }
      },
      "required": ["id", "title", "data", "type"]
    }
  }
}

关键调整说明 #

• 添加全局示例：在requestBody和responses的content中直接定义完整的请求/响应示例，同时在对应的schema中也添加example字段，确保Swagger UI能直接渲染出示例值。
• 明确Tuple结构：使用OpenAPI 3.1的prefixItems替代原有的items数组，更精准地定义固定长度的数组（tuple），同时设置minItems和maxItems为2，约束数组长度。
• 补全嵌套Schema示例：为Id、GetWidgetResponse的每个字段添加具体示例值，让示例内容更真实、清晰。
• 增强约束：给必填字段添加required数组，明确接口的必填参数，提升文档的严谨性。

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