Swagger编辑器显示路径参数的“模式错误：不应有附加属性”错误

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

任何提示？

- Emanuel Ey

Answer 1

这个错误信息有误导性。实际错误是您的路径参数缺失required: true。路径参数始终是必需的，因此请记得将required: true添加到它们中。

- Helen

---

我在定义中加了 required: true，但仍然收到错误提示。 - absay

在我的情况下，我已经使用了“required true”，但仍然出现相同的错误，发现问题是由于缩进不正确导致的。 - Mocas

Answer 2

我也遇到了同样的问题。我在使用Swagger 2.0和OpenAPI 3.0.x时误用了语法。在OpenAPI 3.0.x中，definitions被重新定义为components。在在线编辑器中，你可以点击Edit按钮 > Convert to OpenAPI 3来使用OpenAPI 3.0.x。

关于components的更多信息，请点此.

注：

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

- Ri1a

---

使用在线编辑器以获得更好的错误信息提示的技巧对解决我的问题非常关键。 - Wayne Conrad

你提供的链接 https://editor.swagger.io/ 可以使用，错误信息更加清晰，谢谢！ - Akhha8

Answer 3

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

是的，错误消息极其无用。

- Harold Xie

Answer 4

在我的情况下，我在API定义中缺少参数定义。

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

- Farooq Hanif

Answer 5

在我的情况下，示例的缩进不正确。它是这样的：

              content:
        application/json:
          schema:
            $ref: '#/components/schemas/someresponse'
            examples:
              example1:
                value:
                  param1: "some string"
                  param2: "123"

与其说：

              content:
        application/json:
          schema:
            $ref: '#/components/schemas/someresponse'
          examples:
            example1:
              value:
                param1: "some string"
                param2: "123"

但是使用SwaggerUI预览VScode开放API时没有显示任何错误，一切看起来都是有效的。

- Txugo

Answer 6

语法可能需要两个参数，正如 Helen 所提到的那样 required: true 是必需的，type:DataType 也是必要的。错误信息有误导性。

- Akhil Sharma