Swagger 编辑器显示路径参数的“架构错误：不应有其他属性”错误答案

【问题标题】：Swagger Editor shows the "Schema error: should NOT have additional properties" error for a path parameterSwagger 编辑器显示路径参数的“架构错误：不应有其他属性”错误
【发布时间】：2018-01-14 22:08:09
【问题描述】：

我正在使用http://editor.swagger.io 设计一个 API，但我遇到了一个我不知道如何解决的错误：

Schema error at paths['/employees/{employeeId}/roles'].get.parameters[0]
should NOT have additional properties
additionalProperty: type, format, name, in, description
Jump to line 24

我有以类似方式定义的其他端点，并且没有收到此错误。我想知道缩进或未闭合的引号是否有问题，但似乎并非如此。 Google 似乎也没有提供任何有用的结果。

swagger: "2.0"
info:
  description: Initial draft of the API specification
  version: '1.0'
  title: App 4.0 API
host: api.com
basePath: /v1
tags:
  - name: employees
    description: Employee management
schemes:
  - https
paths:
  /employees/{employeeId}/roles:
    get:
      tags:
        - employees
      summary: "Get a specific employee's roles"
      description: ''
      operationId: findEmployeeRoles
      produces:
        - application/json
      parameters:
        - name: employeeId   <====== Line 24
          in: path
          description: Id of employee whose roles we are fetching
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Role'
        '403':
          description: No permission to see employee roles
        '404':
          description: EmployeeId not found

有什么提示吗？

【问题讨论】：

标签： swagger openapi swagger-2.0 swagger-editor

【解决方案1】：

在我的例子中，我在 api 定义中缺少参数定义

- name: parameterName
  in: query
  description: parameter's description here.
  required: false
  schema:
    type: string

【讨论】：

【解决方案2】：

遇到了同样的问题。我不小心将Swagger 2.0 的语法与Openapi 3.0.x 混淆了。在Openapi 3.0.x 中，定义被重新定义为组件。在online editor 中，您可以点击按钮Edit > Convert to OpenAPI 3 以使用Openapi 3.0.x。

阅读更多关于组件here。

备注：

OAS 3 是最新版本的 OpenAPI 规范。

【讨论】：

使用在线编辑器获得更好的错误消息的技巧是解决我的问题的关键。
您指向editor.swagger.io 的链接有效，错误消息更好，谢谢！

【解决方案3】：

语法 requires 可能需要两个参数，正如 Helen required: true 所提到的，type:DataType 也是需要的。该错误具有误导性。

【讨论】：

【解决方案4】：

错误信息具有误导性。实际错误是您的路径参数缺少required: true。路径参数始终是必需的，所以记得在其中添加required: true。

【讨论】：

我的定义中有required: true，但我仍然收到该错误。
在我的情况下，我要求 true 并且仍然是相同的错误，发现问题是缩进错位