如何在Swagger UI中显示复杂的嵌套整数数组

Question

我的一个POST端点有一个复杂的整数嵌套数组。如何在Swagger UI中显示此结构？

{
"raw_data": [
[
[1,2], [4,5], [7,8]
],
[
[
[1,2], [4,5], [7,8]
]
]
]
}

我正在使用：

openapi："；3.0.0〃
Swagger jsdoc:"6.2.5">
Swagger ui express："4.3.0">
节点：v18.8.0

Answer 1

OpenAPI 3.0.x/3.1

此示例使用oneOf来处理第一组和第二组整数的不同嵌套级别。

# openapi: 3.0.3
raw_data:
type: array
example: [[[1,2], [4,5], [7,8]], [[[1,2], [4,5], [7,8]]]]
minItems: 2
maxItems: 2
items:
type: array
items:
type: array
items:
oneOf:
- type: integer
- type: array
items:
type: integer

仅限OpenAPI 3.1

由于第一组和第二组整数具有不同的嵌套级别，因此可以使用prefixItems关键字来定义每组的确切嵌套级别。您还可以将minItems和maxItems添加到内部数组中，以定义它们的确切长度。

这个定义比上面的oneOf版本更详细，但它更准确地描述了结构。

# openapi: 3.1.0
raw_data:
type: array
# You can add the example for the root array itself, or split it into separate examples of inner arrays
example: [[[1,2], [4,5], [7,8]], [[[1,2], [4,5], [7,8]]]]
minItems: 2
maxItems: 2
prefixItems:
# The 1st set of integers
- type: array
items:
type: array
items:
type: array
items:
type: integer
example: [[1,2], [4,5], [7,8]]  # optional example
# The 2nd set of integers
- type: array
items:
type: array
items:
type: array
items:
type: array
items:
type: integer
example: [[1,2], [4,5], [7,8]]  # optional example

Answer 2

假设你每次都需要这个精确的数组，你可以这样做：

"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"raw_data": {
"type": "array",
"items": {
"type": "integer"  
},
"example": [[[1,2], [4,5], [7,8]], [[[1,2], [4,5], [7,8]]]]
}
}
}
}
}
}

上面使用的示例显示了出来，但就像@Helen提到的那样，您确实需要确保type是一个数组，而不是整数。