在 Spring Boot OpenAPI 中为 List<> 响应生成类型#ref

Question

我被要求在 Spring Boot 中生成以下 OpenAPI 定义：

"responses": {
  "200": {
    "description": "Successful operation",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Entities"
        }
      }
    }
  }
}
...
"components": {
  "schemas": {
    "Entities": {
      "type": "array",
      "description": "Some description",
      "items": {
        "$ref": "#/components/schemas/Entity"
      }
    },
    "Entity": {
      "type": "object",
      ...
    }
  }
}

控制器返回的类型是

List<Entity>

，所以它是一个没有周围对象的JSON数组：

[{}, {}, {}]

我怎样才能做到？是否可以仅使用注释生成它？

我试图通过以下注释来实现它：

@PostMapping("/entities")
@ApiResponse(responseCode = "200", description = "Successful operation", content = {
       @Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
                array = @ArraySchema(schema = @Schema(name = "Entities",
                                                      description = "Some description",
                                                      implementation = Entity.class)))
    })
public List<Entity> getEntities() { ... }

但我得到的是 responses 块中的直接实体 #ref，没有

Entities

方案和“Some description”：

responses": {
  "200": {
    "description": "Successful operation",
    "content": {
      "application/json": {
        "schema": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Entity"
          }
        }
      }
    }
  }
}
...
"components": {
  "schemas": {
    "Entity": {
      "type": "object",
      ...
    }
  }
}