61

I'm using http://editor.swagger.io to design an API and I get an error which I don't know how to address:

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

I have other endpoints defined in a similar way, and don't get this error. I wondered if I had some issue with indentation or unclosed quotes, but that doesn't seem to be the case. Google also did not seem to provide any useful results.

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

Any Hints?

Helen
  • 87,344
  • 17
  • 243
  • 314
Emanuel Ey
  • 2,724
  • 5
  • 30
  • 38

6 Answers6

40

The error message is misleading. The actual error is that your path parameter is missing required: true. Path parameters are always required, so remember to add required: true to them.

Helen
  • 87,344
  • 17
  • 243
  • 314
  • 11
    I have `required: true` in my definition and I'm still getting that error. – absay Sep 12 '18 at 18:10
  • 1
    In my case, I had required true and still the same error, found that the issue was indentation of get misplaced – Mocas Aug 24 '20 at 10:48
33

Had the same problem. I accidentally mixed up the syntax from Swagger 2.0 with Openapi 3.0.x. In Openapi 3.0.x, definitions are redefined as components. In the online editor you can click on the button Edit > Convert to OpenAPI 3 to use Openapi 3.0.x.

Read more about components here.

Remark:

OAS 3 is the latest version of the OpenAPI Specification.

Ri1a
  • 737
  • 9
  • 26
4

For me the cause of the error was a missing a leading slash in the path (internal/resource instead of /internal/resource).

And yes the error message is extremely unhelpful.

Harold Xie
  • 41
  • 1
2

In my case I was missing parameter definition in api definition

- name: parameterName
  in: query
  description: parameter's description here.
  required: false
  schema:
    type: string
Farooq Hanif
  • 1,779
  • 1
  • 15
  • 22
2

In my case it had the wrong indentation for the example. It was:

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

Rather than:

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

But the VScode open api preview with swaggerUI didn't show any errors and everything looked valid.

Txugo
  • 5,008
  • 5
  • 33
  • 40
0

The syntax requires might require two parameters, as mentioned by Helen required: true is need so is type:DataType . The error is misleading.

Akhil Sharma
  • 345
  • 2
  • 13