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

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: [e-mail]
  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: [e-mail]
        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.

[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