swagger - 如何在 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

example关键字不支持 $ref ，而 OpenAPI 2.0 没有办法引用外部示例。

您需要 OpenAPI 3.0 ( openapi: 3.0.0 ) 能够引用外部示例。 OAS3 提供 externalValue 为此目的的关键字:

openapi: 3.0.2
...

      responses:
        '200':
          description: Taxable Entities
          content:
            application/json:
              schema:
                type: object
              examples:
                myExample:  # arbitrary name/label
                  externalValue: 'https://myserver.com/examples/taxable_entity_example.json'

externalValue可以是绝对或相对 URL。注意相对 externalValue URL 是根据 API 服务器 URL ( servers[*].url ) 而不是 API 定义文件的位置解析的。

Swagger UI 和 Swagger Editor 用户注意事项:目前(截至2019年12月) externalValue的内容不显示示例。关注 this issue更新。