どのように参考文献を使用してスガッガー？

Question

JSON仕様：

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

結果：

しかし、私は必要があります。

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

がどのようにカスタム形式の応答のための例の配列に$、参考文献を使用することができますか？ これは典型的なケースですが、ドキュメントが見つかりませんでした。フィードバックいただきありがとうございます。

Answer 1

インライン例は$refをサポートしていない - の例では、完全な例である必要があります。

 "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 
      } 
      } 
     } 
     } 

代わりresponses.<code>.examplesを使用して、あなたがあなたのBaseResponseスキーマに例の値を指定することができ、かつ闊歩UIがそれらを使用します。代わりに。

"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 
     } 
    } 
    } 

またはプロパティレベルの例を使用します：たとえば

、あなたはBaseResponseスキーマに完全な例を追加することができます

"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    // <------ 
     }, 
     ... 
     } 
    } 
    } 

私は"errors": nullと"example": nullがあることに注意したいのですがOpenAPI 2.0（fka Swagger）では実際には有効ではありません。nullable型をサポートしていないためです。 OpenAPI 3.0ではヌル可能型はsupportedのみです。