Swagger 響應資料 response 裡包含動態變化的物件 key 的方法

先說遇到的問題，API 響應資料裡的物件 key 是動態變化的：

如上圖，響應資料裡的物件 key 就是某條資料的唯一標識，根據查詢引數，返回的響應資料是不同的，所以紅框的 key 不是固定的。

大多數情況下，我們只要求 Swagger 資料模型物件 key 是「固定不變」的，下面是「固定不變」的參考寫法：

responses:
  200:
    description: 響應成功
    schema:
      type: object
      properties:
        code:
          type: integer
          description: 響應碼
        msg:
          type: string
          description: 響應描述
        data:
          type: object
          description: 響應資料
          properties:
            id:
              type: integer
              description: 下載任務id
            task_code:
              type: string
              description: 下載任務唯一標識
            url:
              type: string
              description: 下載任務的下載url
            dir:
              type: string
              description: 下載任務的儲存目錄
            out:
              type: string
              description: 下載任務的儲存檔名
            aria2_status:
              type: string
              description: |
                aria2的狀態(<https://aria2.github.io/manual/en/html/aria2c.html#aria2.tellStatus>)
            aria2_gid:
              type: string
              description: aria2的gid
            down_node_server:
              type: string
              description: 下載節點uri

要讓 Swagger 的資料模型允許動態變化的物件 key，可以使用 OpenAPI 規範裡的 additionalProperties 屬性：

responses:
  200:
    description: 響應成功
    schema:
      type: object
      properties:
        code:
          type: integer
          description: 響應碼
        msg:
          type: string
          description: 響應描述
        data:
          type: object
          description: 響應資料
          additionalProperties:
            type: object
            description: 下載任務唯一標識
            properties:
              id:
                type: integer
                description: 下載任務id
              task_code:
                type: string
                description: 下載任務唯一標識
              url:
                type: string
                description: 下載任務的下載url
              dir:
                type: string
                description: 下載任務的儲存目錄
              out:
                type: string
                description: 下載任務的儲存檔名
              aria2_status:
                type: string
                description: |
                  aria2的狀態(<https://aria2.github.io/manual/en/html/aria2c.html#aria2.tellStatus>)
              aria2_gid:
                type: string
                description: aria2的gid
              down_node_server:
                type: string
                description: 下載節點uri

additionalProperties 屬性的用法在我看來和 properties 是一樣一樣的，只是在 OpenAPI 規範裡，使用 additionalProperties 就表示物件的 key 是動態可變的字串。

使用了 additionalProperties 屬性之後，Swagger UI 裡的 Model 截圖，可以看到物件 key 是 * 符號。

參考文章：

• hashmap - Swagger complex response model with dynamic key value hash maps - Stack Overflow
• additionalProperties in Swagger-OpenAPI 2.0 Schemas
• Dictionaries, Hashmaps, Associative Arrays

本作品採用《CC 協議》，轉載必須註明作者和本文連結