Swagger UI 中套接字 io 请求的描述

Question

我想描述一下socketio的路线

/get

。请求看起来像：

["get",{"id":"66ab972245a202801187dce8"}]

以及回应：

["answer",{"id":"66ab972245a202801187dce8", ...}] 

我已经有了

answer

和

id

的架构。

我开始这样描述它：

"/get": {
      "post": {
        "tags": ["widgets"],
        "summary": "ws://localhost:8080",
        "operationId": "getWidget",
        "servers": [
          {
            "url": "ws://localhost:8080"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SocketWidgetRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Widget details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SocketWidgetResponse"
                }
              }
            }
          }
        }
      }
    }

"SocketWidgetResponse": {
        "type": "array",
        "items": [
          {
            "type": "string",
            "example": "answer"
          },
          {
            "$ref": "#/components/schemas/GetWidgetResponse"
          }
        ]
      },
      "SocketWidgetRequest": {
        "type": "array",
        "items": [
          {
            "type": "string",
            "example": "get"
          },
          {
            "$ref": "#/components/schemas/Id"
          }
        ]
      }

id

的架构：

"Id": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true
          }
        }
      }

小部件的布局：

"GetWidgetResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "object"
          },
          "folderId": {
            "type": "string",
            "nullable": true
          },
          "icon": {
            "type": "string",
            "nullable": true
          },
          "data": {
            "type": "object"
          },
          "type": {
            "type": "string"
          }
        }
      }

但是我的 Swager UI 在示例值字段中为空：

我需要以某种方式去做，但我不知道如何做得漂亮、正确、清晰。

Answer 1

您的请求和响应结构是元组，这需要 OpenAPI 3.1 才能获得适当的支持。 （您似乎正在使用 OpenAPI 3.0.x。）

您需要按如下方式更改架构。请注意使用

prefixItems

而不是

items

；

"type": ["string", "null"]

代替

"nullable": true

；和

examples

而不是

example

。

{
  "openapi": "3.1.0",
  ...

  "components": {
    "schemas": {
      "Id": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SocketWidgetResponse": {
        "type": "array",
        "prefixItems": [
          {
            "type": "string",
            "examples": [
              "answer"
            ]
          },
          {
            "$ref": "#/components/schemas/GetWidgetResponse"
          }
        ],
        "minItems": 2,
        "maxItems": 2
      },
      "SocketWidgetRequest": {
        "type": "array",
        "prefixItems": [
          {
            "type": "string",
            "examples": [
              "get"
            ]
          },
          {
            "$ref": "#/components/schemas/Id"
          }
        ],
        "minItems": 2,
        "maxItems": 2
      },
      "GetWidgetResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "object"
          },
          "folderId": {
            "type": [
              "string",
              "null"
            ]
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}

Swagger UI 目前不支持生成

prefixItems

的示例，因此默认情况下它将显示请求和响应示例为

[null, null]

:

要解决此问题，您可以手动添加

SocketWidgetRequest

和

SocketWidgetResponse

的架构级示例：

  "SocketWidgetRequest": {
    "type": "array",
    "prefixItems": [ ... ],
    ...

    "examples": [

      // Custom example for the schema
      [
        "get",
        {
          "id": "66ab972245a202801187dce8"
        }
      ]

    ]
  }

现在你会看到：