Swagger Editor显示路径参数的"架构错误:不应该有其他属性"错误

Question

我正在使用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

我有其他端点以类似的方式定义,并没有得到此错误.我想知道我是否有一些缩进或未公开引号的问题,但似乎并非如此.谷歌似乎也没有提供任何有用的结果.

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

任何提示？

Answer 1

错误消息具有误导性.实际错误是您的路径参数丢失required: true.路径参数始终是必需的,因此请记住添加required: true它们.

Answer 2

有同样的问题。我不小心混淆了Swagger 2.0与Openapi 3.0.x. 在 中Openapi 3.0.x，定义被重新定义为组件。在在线编辑器中，您可以单击按钮Edit > Convert to OpenAPI 3 to use Openapi 3.0.x.

在此处阅读有关组件的 更多信息。

评论：

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

Answer 3

对我来说，错误的原因是路径中缺少前导斜杠（internal/resource而不是/internal/resource）。

是的，错误消息非常没有帮助。