Swagger 中的关联数组 (OpenApi 3.0.0)答案

【问题标题】：Associative array in Swagger (OpenApi 3.0.0)Swagger 中的关联数组 (OpenApi 3.0.0)
【发布时间】：2020-11-05 11:41:24
【问题描述】：

我有一个 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"
    }
  ]
}

如何在文档中大摇大摆地显示 data 这是键的名称？

至于现在我只在招摇中得到嵌套数组：

[
  {
    "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"
    }
  ]
]

我需要 data 键在从 API 返回时以大张旗鼓的方式显示。可行吗？我还没有找到任何解决方案...：/

我的 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"

任何帮助将不胜感激:)

干杯

【问题讨论】：

标签： swagger associative-array openapi

【解决方案1】：

尝试在 assoc-array 的中间层中使用“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"

【讨论】：