如何在OpenAPI（Swagger）中指定多個404原因？

Question

我正在爲嵌套資源（屬於傳遞的內容）定義路徑。如果客戶端得到404，那麼可能是因爲未找到傳遞ID，或者傳遞未包含任何指定類型的內容。

如何建模使用OpenAPI（YAML）？

我有現在這個權利...

paths: 
    '/deliveries/{id}/content/articles': 
    get: 
     summary: Retrieves articles from a delivery 
     description: Retrieves all articles from a single delivery 
     [...] 
     responses: 
     '200': 
      description: articles found 
      schema: 
      $ref: '#/definitions/Article' 
     '404': 
      description: delivery not found 
      schema: 
      $ref: '#/definitions/Error' 
     '404': 
      description: delivery did not contain any articles 
      schema: 
      $ref: '#/definitions/Error' 

...但是當我保存JSON從揚鞭編輯器，它dropps除了最後一個所有404個響應（「送貨時沒有包含任何文章「）。

Answer 1

OpenAPI/Swagger 2.0中不允許每個狀態碼的多個響應類型，但在OpenAPI 3.0 by using oneOf中受支持。

在OpenAPI的2.0，你只能擁有一個404響應一個模式：

 responses: 
     '404': 
      description: delivery not found, or delivery did not contain any articles 
      schema: 
      $ref: '#/definitions/Error' 

... 
definitions: 
    Error: 
    type: object 
    properties: 
     status: 
     type: integer 
     type: 
     type: string 
     message: 
     type: string 

其中Error有效載荷就可以了，說：

{ 
    "status": 404, 
    "type": "DeliveryNotFoundError", 
    "message": "delivery not found" 
} 

{ 
    "status": 404, 
    "type": "NoArticlesInDeliveryError", 
    "message": "delivery did not contain any articles" 
}