Parameters in swagger:route produce validation warnings

[mhr3]

Problem statement

When generating a spec from source, specifying parameter types in swagger:route can produce warnings during validation.

Steps to reproduce

	/* swagger:route PUT /pet/{id} pets users updatePet
	Update a pet based on the parameters.
	Parameters:
	+ name:        id
	  description: The pet id
	  in:          path
	  type:  string
	  required:    true
	+ name:        request
	  description: The request model.
	  in:          body
	  type:        petModel
	Responses:
	200: body:someResponse
	422: body:validationError
 */

The above definition produces:

        ...
        "parameters": [
          {
            "type": "string",
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "type": "object",
            "name": "request",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "$ref": "#/definitions/petModel"
            }
          }

Few issues in the generated spec:

• the type: object is invalid outside of the schema object
• the schema: { type: string } is invalid
• IMO path parameters should default to type: string automatically (afterall type is required there)

Environment

swagger version: 0.17.2
go version: 1.11
OS: linux

[casualjim]

the syntax in the doc comments is wrong.
https://goswagger.io/use/spec/route.html

[mhr3]

The docs don't even mention a way to do this, I went by the tests, still, that's a separate issue, no?

[casualjim]

You link parameters through parameter structs, not by defining them in the location where you did.

If you want to define things like this, there is swagger:operation which allows you to put the yaml for the operation instead

[mhr3]

I'm aware of swagger:parameters, but I found it difficult to deal with the disconnect between routes and their params, this way to define them in swagger:route was more natural. Any plans to keep this direction of defining it as well? IMO being able to link a route to the param structs would make things nicer to use, ie:

// swagger:param
type PetIDParam struct {
  // in: path
  ID string
}

...
swagger:route GET /pets/{id} getPet
Parameters: PetIDParam

Basically similar to how responses are defined (though params should accept n definitions, not just one)

[casualjim]

you can use swagger:operation for that

https://goswagger.io/use/spec/operation.html

[mhr3]

Right, but that uses raw yaml, I'd rather have stronger consistency guarantees.