Swagger-editor: Misleading error message claiming allowed values in "in" of a parameter only "query, header, cookie" without "path"

[bingtimren]

Q&A (please complete the following information)

• OS: Linux
• Browser: Firefox
• Version: 61.0.1
• Method of installation: docker
• Swagger-Editor version: swaggerapi/swagger-editor docker image,latest,image ID 9fb9dba980ed
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Example Swagger/OpenAPI definition:

openapi: 3.0.1
info:
  title: Contact List API
  description: CRUD a simple Contact item.
  version: '0.1'
  termsOfService: ''
  contact:
    name: Bing Ren
    email: [email protected]
  license:
    name: Free to use
    url: ''
servers:
  - url: 'http://localhost:8080/contactList/0.1/'
    description: SAM local api
paths:
  /contact:
    get:
      summary: Get contacts as a list
      description: Get a list of contacts
      operationId: getContactAsList
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '404':
          description: Not found response
          content:
            text/plain:
              schema:
                title: Weather not found
                type: string
                example: Not found
  /contact/{contactId}:
    get:
      summary: Get a single contact by Id
      operationId: getContactById
      parameters: 
        - name: contactId
          in: path
          description: ID of contact to return
          required: true
          # schema:
            # type: integer
            # format: int64
security:
  - app_id: []
components:
  schemas:
    ContactList:
      title: Contact List
      type: array
      items:
        $ref: '#/components/schemas/Contact'
    Contact:
      title: Contact Item
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          description: Internal parameter
          format: int32
          example: 8166
        name:
          type: string
          description: Contact's full name
          example: Winston Smith
        email:
          type: string
          description: Email
          example: [email protected]
        phone:
          type: string
          description: Phone number
          example: [phone]
          pattern: '\+[0-9 ]+'
        age:
          type: integer
          description: Age
          format: int32
          example: 40
          minimum: 0
          maximum: 150
  securitySchemes:
    app_id:
      type: apiKey
      description: >-
        API key to authorize requests. If you don't have an OpenWeatherMap API
        key, use `fd4698c940c6d1da602a70ac34f0b147`.
      name: appid
      in: query

Swagger-Editor configuration options:

I didn't configure the editor, just launched the docker image

Describe the bug you're encountering

This is a file I'm working on. When I still have not defined the schema for a path parameter, editor reports an error at the "in" property, claiming the allowed values are only "query, header, cookie". This is very confusing and in fact wrong. If I just complete the parameter definition by providing it's schema, this error is not reported, although the value for "in" is still "path".

As a learner myself to the OpenAPI specification I was quite confused by the misleading error, and spent much time consulting with documents and examples, then finally concluded that it's a false alarm.

Schema error at paths['/contact/{contactId}'].get.parameters[0].in
should be equal to one of the allowed values
allowedValues: query, header, cookie
Jump to line 43

To reproduce...

Steps to reproduce the behavior:

Load the sample definition

Expected behavior

The error should not be reported in the first place. Or, if that's not possible or difficult, at least make the message not so misleading.

Screenshots

See above

Additional context or thoughts

[shockey]

Hi @bingtimren, thanks for the report 😄

This is, indeed, an error quality issue. Behind the scenes, the validation engine is trying to match your parameter against an internally-defined schema for a Path Parameter Object, but doesn't match because schema is missing. Since it doesn't match, it assumes that it's a generic Parameter Object... so you get weird errors.

[ncamn]

Like @bingtimren, I am learning the OpenAPI specification and got the same misleading error by forgetting the required field instead of the schema one. In addition, I got a second misleading error: should match exactly one schema in oneOf even if I didn't provided any oneOf field in schema.

This is the file I'm working on, as an example, and the corresponding errors below:

openapi: '3.0.1'
info:
  title: My API
  version: 0.1.0
paths:
  '/':
    get:
      responses:
        '200':
          description: OK
  '/audits':
    get:
      responses:
        '501':
          description: Not Implemented
      tags:
        - audits
  '/audits/{auditId}':
    parameters:
      - in: path
        name: auditId
        # required: true
        schema:
          type: integer
          format: int64
    get:
      responses:
        '501':
          description: Not Implemented
      tags:
        - audits

Schema error at paths['/audits/{auditId}'].parameters[0]
should match exactly one schema in oneOf
Jump to line 20

Schema error at paths['/audits/{auditId}'].parameters[0].in
should be equal to one of the allowed values
allowedValues: query, header, cookie
Jump to line 20

I am aware that the required field is marked as REQUIRED in the specification, but the errors shown are still misleading though.

[ChristianDavis]

Is a fix for the validator in the works, or still an open issue?

[shockey]

@ChristianDavis no one is working on it currently, it’s a pretty general issue with the JavaScript JSONSchema validation libraries. Big thing that we want to tackle, but of course there are smaller, more pressing things.

If you feel up to the task, let me know here, and I’ll share some more context.

[Gp2mv3]

Still no news ? We also have this issue.

[cfkxzsat]

Same here

[sevakalashnikov]

I just ran into the same issue, if I remove required="true" I got

should match exactly one schema in oneOf
Jump to line 101

should be equal to one of the allowed values
allowedValues: query, header, cookie
Jump to line 102

If I add required="false" I got

should be equal to one of the allowed values allowedValues: true

[raminsiblack]

The schema and required fields are not even required based on 3.0.0 openapi spec. Why it needs them to be required ?!

[eneko]

This error happens not only on the editor (http://editor.swagger.io), but also on Swagger UI itself (when hosted).

Adding schema to the parameters solves the issue (no idea why is required, though):

      parameters: 
        - name: contactId
          in: path
          description: ID of contact to return
          required: true
          schema:
            type: integer
            format: int64

[sirolf2009]

Adding the schema does nothing for me. I copied the first example from this page: https://swagger.io/docs/specification/describing-parameters/

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get

and I still get errors:

should be equal to one of the allowed values allowedValues: body, header, formData, query
should NOT have additional properties additionalProperty: schema, in, name, required, description 

[eneko]

@sirolf2009 have you tried specifying the format for that integer field?

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
            format: int64
          required: true
          description: Numeric ID of the user to get

[sirolf2009]

@eneko just tried it, still got errors
This line get: gives me should have required property 'responses' missingProperty: responses
This line - in: path gives me should be equal to one of the allowed values allowedValues: body, header, formData, query

[kurt-o-sys]

same here:

for this:

  /api/rss/{periodicity}:
    get:
      summary: rss feed
      operationId: getRss
      parameters:
        - name: periodicity
          in: path
          description: periodicity of the rss feed
          required: false
          schema:
            type: string

[kurt-o-sys]

oh, sorry, I see, path parameters must be true...

[eneko]

@kurt-o-sys correct, path parameters must have required: true.

@sirolf2009, seems like you are missing the responses section for your get endpoint.

The following spec contains both of your examples, and properly validates at https://editor.swagger.com

openapi: '3.0.1'
info:
  title: My API
  version: 0.1.0
paths:
  '/':
    get:
      responses:
        '200':
          description: OK
  '/audits':
    get:
      responses:
        '501':
          description: Not Implemented
      tags:
        - audits
  '/audits/{auditId}':
    parameters:
      - in: path
        name: auditId
        required: true
        schema:
          type: integer
          format: int64
    get:
      responses:
        '501':
          description: Not Implemented
      tags:
        - audits
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
            format: int64
          required: true
          description: Numeric ID of the user to get
      responses:
        '200':
          description: OK
  /api/rss/{periodicity}:
    get:
      summary: rss feed
      operationId: getRss
      parameters:
        - name: periodicity
          in: path
          description: periodicity of the rss feed
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK

[sirolf2009]

@eneko I did have a responses part, but on closer inspection, I had

swagger: '2.0'

instead of

openapi: '3.0.1'

Updating that fixed it

[shockey]

I've opened a pull request (#1985) that will close this issue.

Here's what Swagger Editor reports with my changes:

Structural error at paths./contact/{contactId}.get.parameters.0
should have either a `schema` or `content` property 

[Gabb1995]

For me it shows that query is not allowed using openapi 3.0.1

Structural error at paths./whitelabels.get.parameters.6.in should be equal to one of the allowed values allowedValues: path, header, cookie

      parameters:
      - in: header
        name: x-authtoken
        description: The authtoken you receive from login
        schema:
          type: string
        required: true
      - in: query
        name: page
        required: true
        schema:
          type: integer
        description: The page number so if limit is 5 and there are 15 results, there will be 3 pages (0, 1, 2)

Seems to fix itself after a hard refresh of the webpage on editor.swagger.io