Question

在我的Swagger规范文件中，我想返回示例响应，因为我可以添加examples作为响应。但这使我的spec文件非常大且容易出错。有没有办法引用包含示例对象的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

如何在Swagger中引用包含响应示例的外部JSON文件？

1 个答案: