I want to describe the route /get for socketio. The request looks like:
["get",{"id":"66ab972245a202801187dce8"}]
and the response:
["answer",{"id":"66ab972245a202801187dce8", ...}]
I already have a schema for the answer and id.
I started to describe it like this:
"/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"
}
]
}
The schema for the id:
"Id": {
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": true
}
}
}
The layout for the widget:
"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"
}
}
}
But my Swager UI is empty in the example value field:
I need to do it somehow, but I have no idea how to do it beautifully, correctly and clearly.
You request and response structures are tuples, this requires OpenAPI 3.1 for proper support. (You seem to be using OpenAPI 3.0.x.)
You’ll need to change the schemas as follows. Note the use of prefixItems instead of items; "type": ["string", "null"] instead of "nullable": true; and examples instead of 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 currently does not support generating examples for prefixItems, so by default it will show the request and response examples as [null, null]:
To work around the issue, you can add schema-level examples for SocketWidgetRequest and SocketWidgetResponse manually:
"SocketWidgetRequest": {
"type": "array",
"prefixItems": [ ... ],
...
"examples": [
// Custom example for the schema
[
"get",
{
"id": "66ab972245a202801187dce8"
}
]
]
}
Now you will see: