Question

我正在尝试使用swagger editor生成API文档。我将API规范指定为以下

paths:
  /opendata/v1/{index}:
    get:
      tags: [verification]
      description: Verify the person information
      parameters:
        - name: index
          in: path
          description: specific data index
          required: true
          type: string
        - name: name
          in: query
          description: name of a person
          required: false
          type: string
        - name: company name
          in: query
          description: name of a company
          required: false
          type: string

      responses:
        '200':
          description: Success
          content:
            application/json:
              schemas:
                $ref: '#/responses/200'



responses:
    '200':
      description: Success
      schema:
        type: object
        properties:
          verification:
            type: string

但它始终在编辑器中显示错误“不是有效的响应定义”。我检查了here的响应规范。我应该做些什么改变，以免错误发生。

注意：我希望json形式的响应如下：

{
    verification:string
}

Answer 1

您正在混合使用OpenAPI / Swagger 2.0和OpenAPI 3.0语法。您的规范似乎是swagger: '2.0'，因此您应该使用：

paths:
  /opendata/v1/{index}:
    get:
      ...

      produces:
        - application/json
      responses:
        200:
          $ref: '#/responses/200'

这是一个相关的OpenAPI / Swagger 2.0指南：Describing Responses

Swagger编辑器在指定响应“不是有效的响应定义”时抛出错误

1 个答案: