Validation Parameters, vague errors that have regressed ( I believe )

[ponelat]

Q	A
Bug or feature request?	Bug ( regression )
Which Swagger/OpenAPI version?	2.0
Which Swagger-Editor version?	swaggerEditor/Ui: "3.1.9/g95b3f38a-dirty" / version: "3.2.2" / gitRevision: "g774a066"
How did you install Swagger-Editor?	Custom + Using Online version
Which broswer & version?	Chrome/59
Which operating system?	Linux Mint 18

Demonstration API definition

swagger: '2.0'
info:
  version: '1'
  title: oneOf validation fail
  description: ok

paths:
  /models/{name}:
    get:
      summary: Extra `example` field in parameter
      description: ok
      parameters: 
      - in: path
        name: name
        type: string
        required: true
        example: ok
      responses:
        200:
          description: Ok

Expected Behavior

Validation should show that the "example" key is not allowed in "path" parameters.

Current Behavior

Two validation errors occur...

should NOT have additional properties
additionalProperty: type, example, in, name, required
Jump to line 13
Schema error at paths['/models/{name}'].get.parameters[0].in
should be equal to one of the allowed values
allowedValues: body, header, formData, query
Jump to line 13

Possible Solution

Hack the structural validation lib, to better handle oneOf cases?
Ie: in: path then enforce validation for path items.
Or catch the strings ( this was done before and has regressed ) and transform the error message.
And perhaps lastly, add custom validation to the cases where oneOf appear, and remove the bad structural messages.

Context ( as a user )

Frustration on how to fix the spec, given the vague somewhat incorrect validation messages.

[webron]

Yeah, that's a regression caused by changing the JSON Schema validator. We really need to address this.

[freegnu]

adding required: true to the parameter definition fixes the problem. Removing it from any path parameter definition causes the error. Maybe a better default for path parameters?

[shockey]

@freegnu that would be nice, but would require a change to the OpenAPI specification!

It currently reads:

Parameter.required

Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false.

If we just transparently added required: true in the UI/Editor, it would be out of line with the specification and confusing to end-users. It may also break other Swagger/OpenAPI tools that don't transparently add required: true.

That said, I don't think it'd be a terrible idea to change the specification to something like if the parameter location is "path", this property's default value is true, and MAY explicitly be set to true.

Feel free to bring it up with the OpenAPI folks here: https://github.com/OAI/OpenAPI-Specification/issues

[bmschwa]

Anyone still seeing this? I'm having the same problem today (1 year after the last entry).... Or have an example of a way to work around it? for us swagger Novices, a oneOf workaround example would be helpful

[dsandor]

@bmschwa Hi Brian, I just came across this issue today and found a solution. It seems much of the examples I see ask you to specify the parameters in such a way that does not pass validation. Here is a working example that got me past this issue.

FWIW, I really wish the validation failures provided links to working examples. This would mitigate a lot of frustration because there is so much incorrect or no longer valid examples online.

/my/path/{id}:
  get:
    parameters:
    -name: id
      in: path
      required: true
      type: string

. . .

For me the change was to specify type: string instead of the long form where I was specifying the schema for the type. I think that is what threw off validation for me.

The documentation here: https://swagger.io/docs/specification/describing-parameters/ tells us to describe the path parameters with schema which does not work in the editor. You must (as of today) specify the type on a single line in short form e.g. type: integer or type: string`.

[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 […]parameters.0
should NOT have additional properties
additionalProperty: example