Swaggerで応答例を含む外部JSONファイルを参照する方法は？

Question

私のSwagger仕様ファイルでは、回答の例を返信したいのですが、そのためにはexamplesを追加することができます。しかし、それは私の仕様ファイルをかなり大きくエラーを起こしやすいものにしています。サンプルオブジェクトのJSONを含むファイルを参照する方法はありますか？

私は以下のように試しましたが、うまくいかないようです。

get: 
    tags: 
    - businesses 
    summary: Get Taxable Entities details 
    description: '' 
    operationId: getTaxableEntities 
    produces: 
    - application/json 
    parameters: 
    - name: business_id 
     in: path 
     required: true 
     type: integer 
     format: int32 
    - name: gstIn 
     in: query 
     required: false 
     type: integer 
     format: int32 
    responses: 
    '200': 
     description: Taxable Entities 
     schema: 
     type: file 
     default: 
      $ref: taxable_entity_example.json 
    '401': 
     description: You are not authorised to view this Taxable Entity 

Answer 1

まず第一に、あなたのスペックは有効ではありません - application/json応答は、オブジェクト・スキーマではなく、ファイルのスキーマを必要としています。

$refを正しく使用していますが、（default）ではなくexampleというキーを使用してスキーマの例が指定されています（Swaggerでは意味が異なります）。

実施例は次のようになります

responses: 
    '200': 
     description: Taxable Entities 
     schema: 
     type: object 
     properties: 
      id: 
      type: integer 
      format: int32 
      name: 
      type: string 
     required: 
      - id 
      - name 
     example: 
      $ref: 'taxable_entity_example.json' 

または実施例ファイルは、異なるサブ経路を有する場合：

 example: 
      $ref: '../examples/taxable_entity_example.json' 

または絶対的な基準を使用して：

 example: 
      $ref: 'http://path/to/taxable_entity_example.json' 

taxable_entity_example.jsonには、

{ 
    "id": 1, 
    "name": "foo" 
} 

参考： Reuse Phylosophy > Remote References