在Swagger中創建可重用的數組定義

Question

我正在使用Swagger 2.0開發一個定義/文檔優先API的規範。我已經設法將大多數可重用組件分解爲定義部分，但是我無法弄清楚如何爲常量數組創建可重用定義。

例如，我將返回圖片的一些路徑，像這樣的：

paths: 
    /resource/{imageId}: 
    get: 
     produces: 
     - image/jpeg 
     - image/png 
     - image/gif 
     parameters: 
     - in: path 
      name: imageId 
      type: string 
      required: true 
     responses: 
     200: 
      description: Success 
      schema: 
      type: file 

這工作得很好，但我希望能夠定義值的可重複使用的陣列爲「生成」元素，以便我可以重複使用相同的列表來生成任何圖像的路徑。

下似乎像是一個直觀的方法，但是招搖報告說，imageMimeTypes的定義是無效的：

paths: 
    /resource/{imageId}: 
    get: 
     produces: 
     $ref: "#/definitions/imageMimeTypes" 
     parameters: 
     - in: path 
      name: imageId 
      type: string 
      required: true 
     responses: 
     200: 
      description: Success 
      schema: 
      type: file 
definitions: 
    imageMimeTypes: 
    - image/jpeg 
    - image/png 
    - image/gif 

是否有可能創建一個定義一個這樣的數組？如果是這樣，應該使用什麼語法？

Answer 1

首先，如果這些produces值用於大部分操作中，您可以將它們定義爲全局produces並在必要時覆蓋。

produces: 
    - image/jpeg 
    - image/png 
    - image/gif 

paths: 
    /resource/{imageId}: 
    get: 
     # Inherits global "produces" 
     ... 
    /something: 
    get: 
     # Overrides global "produces" 
     produces: 
     - application/json 
     ... 

你的第二個例子是無效的，因爲produces不能有$ref值。但是你可以使用YAML錨來達到類似的效果。請注意，在使用錨點之前，必須定義錨點，因此您需要將該列表放在路徑定義的上方。

x-types: 
    imageMimeTypes: &IMAGE-MIME-TYPES 
    - image/jpeg 
    - image/png 
    - image/gif 

paths: 
    /resource/{imageId}: 
    get: 
     produces: *IMAGE-MIME-TYPES 
     parameters: 
     - in: path 
      name: imageId 
      type: string 
      required: true 
     responses: 
     200: 
      description: Success 
      schema: 
      type: file 

我把列表擴展的關鍵x-types代替definitions 1），因爲definitions下用於輸入和輸出模式，而不是隨機的名單，和2），以防止揚鞭主編的「未使用的定義」警告。

這適用於（至少）Swagger Editor和Swagger UI。