Wie Sie mehrere 404 Ursachen in OpenAPI (Swagger) angeben?

Question

Ich definiere einen Pfad für eine verschachtelte Ressource (Inhalt gehört zu einer Lieferung). Wenn der Client eine 404 erhält, kann dies entweder der Fall sein, weil die Liefer-ID nicht gefunden wurde, oder die Lieferung enthält keinen Inhalt des angegebenen Typs.

Wie modelliere ich das mit OpenAPI (YAML)?

ich jetzt dieses Recht haben ...

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' 

... aber wenn ich die JSON vom Swagger Editor speichern, Dropps es die alle 404 Antworten mit Ausnahme der letzten ("Lieferung tat nicht irgendwelche Artikel enthalten ").

Answer 1

Mehrere Antworttypen pro Statuscode sind in OpenAPI/Swagger 2.0 nicht zulässig, werden jedoch in OpenAPI 3.0 by using oneOf unterstützt.

In OpenAPI 2.0 können Sie nur ein einziges Schema für eine 404-Antwort haben:

 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 

wo die Error Nutzlast, sagen kann:

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

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