Wie verwenden Sie Ref in Beispiele Swagger?

Question

JSON-Spezifikation:

"responses": { 
      "200": { 
      "description": "Успешный ответ сервиса", 
      "schema": { 
       "$ref": "#/definitions/BaseResponse" 
      }, 
      "examples": { 
       "application/json": { 
       "status": true, 
       "response": { 
        "$ref": "#/definitions/Product" 
       }, 
       "errors": null 
       } 
      } 
      } 
} 

Ergebnis:

Aber ich brauche:

{ 
    "status": true, 
    "response": { 
     "ProductNumber": "number", 
     "Barcode": "number", 
     "Length": 12, 
     "Width": 34, 
     "Height": 423, 
     "Volume": 1232 
    } 
    }, 
    "errors": null 
} 

Wie ich $ Refs in Beispiel Array für benutzerdefiniertes Format Antwort verwenden, kann? Es ist ein typischer Fall, aber ich kann keine Dokumentation dafür finden. Vielen Dank für Ihr Feedback.

Answer 1

Inline Beispiele nicht $ref unterstützen - das Beispiel muss ein vollständiges Beispiel sein:

 "responses": { 
     "200": { 
      "description": "Успешный ответ сервиса", 
      "schema": { 
      "$ref": "#/definitions/BaseResponse" 
      }, 
      "examples": { 
      "application/json": { 
       "status": true, 
       "response": { 
       "ProductNumber": "number", 
       "Barcode": "number", 
       "Length": 12, 
       "Width": 34, 
       "Height": 423, 
       "Volume": 1232 
       }, 
       "errors": null 
      } 
      } 
     } 
     } 

Statt responses.<code>.examples zu verwenden, können Sie die Beispielwerte in Ihrem BaseResponse Schema angeben, und Swagger UI werden diejenigen verwenden stattdessen.

Zum Beispiel können Sie ein komplettes Beispiel zu Ihrem BaseResponse Schema hinzufügen:

"definitions": { 
    "BaseResponse": { 
     "type": "object", 
     "properties": { 
     "status": { 
      "type": "boolean" 
     }, 
     ... 
     }, 
     "example": { // <------ schema-level example 
     "status": true, 
     "response": { 
      "ProductNumber": "number", 
      "Barcode": "number", 
      "Length": 12, 
      "Width": 34, 
      "Height": 423, 
      "Volume": 1232 
     }, 
     "errors": null 
     } 
    } 
    } 

oder verwenden Eigenschaft Ebene Beispiele:

"definitions": { 
    "BaseResponse": { 
     "type": "object", 
     "properties": { 
     "status": { 
      "type": "boolean", 
      "example": true   // <------ 
     }, 
     "response": { 
      "$ref": "#/definitions/Product" 
     }, 
     "errors": { 
      "example": null   // <------ 
     } 
     } 
    }, 
    "Product": { 
     "type": "object", 
     "properties": { 
     "ProductNumber": { 
      "type": "string", 
      "example": "number"  // <------ 
     }, 
     "Length": { 
      "type": "integer", 
      "example": 12    // <------ 
     }, 
     ... 
     } 
    } 
    } 

würde Ich mag zu beachten, dass "errors": null und "example": null sind ist in OpenAPI 2.0 (fka Swagger) nicht wirklich gültig, da NULL-Typen nicht unterstützt werden. Nullable-Typen sind supported nur in OpenAPI 3.0.