Swagger - Określ opcjonalnej właściwości obiektu lub wiele odpowiedzi

Question

mam API, które albo zwraca następującą odpowiedź na sukces:

{ 
    "result": "success", 
    "filename": "my-filename.txt" 
} 

lub coś poniżej momencie awarii:

{ 
    "result": "error", 
    "message": "You must specify the xxx parameter." 
} 

Obiekt nazwa pliku jest określone tylko, jeśli żądanie zakończyło się sukcesem, ale w przypadku błędu wystąpił komunikat. Oznacza to, że komunikat i właściwości pliku są "opcjonalne", ale właściwość wyniku jest wymagana.

Próbowałem definiowania ten obiekt odpowiedzi w definicji, jak pokazano poniżej:

"my_response_object": { 
    "type": "object", 
    "properties": { 
     "result": { 
      "type": "string", 
      "description": "value of 'success' or 'error', indicated whether was successful", 
      "required": true 
     }, 
     "message": { 
      "type": "string", 
      "description": "an error message if there was an issue", 
      "required": false 
     }, 
     "filename": { 
      "type": "string", 
      "description": "the filename to return if the request was successful", 
      "required": false 
     } 
    } 
} 

Ale wydaje się, że przechwala nie lubi „wymagane” atrybut i pojawi się następujący komunikat o błędzie:

Kiedy patrzę na przykład z przekrętów, mają one następujący układ, w którym istnieją dwie różne definicje odpowiedzi zamiast jednej.

"responses": { 
    "200": { 
     "description": "Profile information for a user", 
     "schema": { 
      "$ref": "#/definitions/Profile" 
     } 
    }, 
    "default": { 
     "description": "Unexpected error", 
     "schema": { 
      "$ref": "#/definitions/Error" 
     } 
    } 
} 

Mogłem to zrobić, ale wygląda na to, że nie można mieć wielu odpowiedzi na 200 kodów błędu. Czy to oznacza, że ​​do wszystkich odpowiedzi na błędy trzeba użyć "domyślnego", a dla wszystkich błędnych odpowiedzi można mieć tylko jedną strukturę, czy też istnieje sposób na określenie, że niektóre atrybuty są opcjonalne w definicjach?

Answer 1

Otrzymujesz błąd w modelu, ponieważ nie jest to sposób definiowania wymaganych właściwości.

Poprawna forma będzie:

"my_response_object": { 
     "type": "object", 
     "required": [ "result" ], 
     "properties": { 
      "result": { 
       "type": "string", 
       "description": "value of 'success' or 'error', indicated whether was successful" 
      }, 
      "message": { 
       "type": "string", 
       "description": "an error message if there was an issue" 
      }, 
      "filename": { 
       "type": "string", 
       "description": "the filename to return if the request was successful" 
      } 
     } 
    } 

Nic nie zakłada własność required być opcjonalne. Należy pamiętać, że oznacza to, że można uzyskać zarównomessage i filename.

Możesz użyć tego modelu do odpowiedzi 200.

Jednak - jeśli chodzi o projektowanie interfejsu API REST, łamie to jeden z bardziej powszechnych standardów. Kody statusowe, pobierane z protokołu HTTP, mają przekazać wynik operacji. 2XX są używane dla pomyślnych odpowiedzi, 4XX dla błędów spowodowanych błędnym wpisem użytkownika, 5XX dla problemów po stronie serwera (3XX dla przekierowań). To, co tu robisz, mówi klientowi - operacja zakończyła się sukcesem, ale w rzeczywistości może to być błąd.

Jeśli wciąż możesz zmodyfikować interfejs API, zdecydowanie zaleciłbym wprowadzenie tego rozróżnienia za pomocą kodów statusu, nawet przy użyciu precyzyjnie dostrojonych rozróżnień, takich jak 200 dla pomyślnej operacji GET, 201 dla pomyślnej operacji POST (lub utworzenia) i tak dalej, w oparciu o definicje tutaj - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.