Swagger中的关联数组(OpenApi 3.0.0)

Question

我有一个API，它总是使用关联数组回答，其中只有一个条目包含包含最终结果的键“数据”。结果可以是一个对象或对象数组。这是API输出：

{
  "data": {
    "id": 1,
    "name": "product1 name",
    "type": "type a",
    "created_at": "2011-09-28T13:20:15+02:00"
  }
}

{
  "data": [
    {
      "id": 1,
      "name": "product1 name",
      "type": "type a",
      "created_at": "2010-09-28T13:20:15+02:00"
    },
    {
      "id": 6,
      "name": "product6 name",
      "type": "type f",
      "created_at": "2010-09-28T13:20:28+02:00"
    },
    {
      "id": 17,
      "name": "product17 name",
      "type": "type Q",
      "created_at": "2010-09-28T13:20:42+02:00"
    }
  ]
}

我怎样才能让swagger在文档中显示数据，即键的名称？

至于现在，我只得到大摇大摆的嵌套数组：

[
  {
    "id": 1,
    "name": "product1 name",
    "type": "type a",
    "created_at": "2010-09-28T13:20:15+02:00"
  }
]

[
  [
    {
      "id": 1,
      "name": "product1 name",
      "type": "type_a",
      "created_at": "2010-01-01T18:21:20+02:00"
    }
  ]
]

我需要数据键在从API返回时以swagger的形式显示。这可行吗？我还没有找到任何解决办法…：/

我的yaml文件的部分内容：

openapi: "3.0.0"
info:
  version: 1.0.0
paths:
  /products/:
    get:
      summary: List all available products
      operationId: listProducts
      tags:
        - products
      responses:
        200:
          description: Array of products
          content:
            application/json:    
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Products"
  /products/{product_id}:
    get:
      summary: Get specific product
      operationId: showProductById
      tags:
        - products
      parameters:
        - name: product_id
          in: path
          required: true
          description: The id of the product to retrieve
          schema:
            type: integer
            format: int32
            example: 1
      responses:
        200:
          description: Product object
          content:
            application/json:
              schema:
                type: array
                properties:
                  datar: string
                items:
                  $ref: "#/components/schemas/Product"
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 10
        name:
          type: string
          example: "producta name"
        type:
          type: string
          example: "type a"
        created_at:
          type: string
          format: date
          example: "2010-01-01T18:21:20+02:00"
    Products:
      type: array
      items:
        $ref: "#/components/schemas/Product"

任何帮助都将不胜感激：）

干杯

Answer 1

尝试在assoc数组的中间层中使用“additionalProperties”，源：https://swagger.io/docs/specification/data-models/dictionaries/

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 10
        name:
          type: string
          example: "producta name"
        type:
          type: string
          example: "type a"
        created_at:
          type: string
          format: date
          example: "2010-01-01T18:21:20+02:00"

    ArrayOfProduct:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/Product"

    Products:
      type: object
      properties:
        data:
          type: object
          $ref: "#/components/schemas/ArrayOfProduct"