如何引用包含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