如何引用包含Swagger中的響應示例的外部JSON文件？

Question

在我的Swagger spec文件中，我想返回示例響應，因爲我可以在響應中添加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時是正確的，但方案示例使用example鍵指定，而不是default（default在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