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

imzhi發表於2020-11-12

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

Swagger 響應資料 response 裡包含動態變化的物件 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 是 * 符號。

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

參考文章:

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

相關文章