Clarify how AllowableValues works

[Bart Meuris]

This is mostly a request for documentation improvement and to clarify how exactly this is supposed to work

On a Parameter, you have the AllowableValues() method, which I would expect to accept a []string - but instead it accepts a map[string]string, and I don't really understand what the purpose of this would be or exactly this map should be constructed to only allow a certain set of values for this specific parameter.

In your go-restful-openapi package (which I also use) I did find a test-case, where it just uses a map with key/value pairs that are every time the same, which seems a bit strange?

[Ernest Micklei]

Hi @bartmeuris , thank you for reporting this. I will have a look at it. First thing that comes to mind is that it indeed reflects what was needed for the openapi.

[Sergey Vilgelm]

@emicklei Could you provid an example of how to use AllowableValues? the test does not help at all. Why it is a map? and where does the validation happens?

[Sergey Vilgelm]

according to this https://github.com/emicklei/go-restful-openapi/blob/2c3ab9bf579ac10ff5dd182469f9c46c6ef33490/build_path.go#L180-L195

the keys are just some internal values, that are not used anywhere, except it used to provide an order of enum values in swagger

only the values are used

[Ernest Micklei]

hi, it seems that indeed it does not make sense for AllowableValues to be a map.
https://swagger.io/docs/specification/data-models/enums/ shows examples with simple arrays of values.
Changing the type of the field AllowableValues is not possible as it breaks backwards compatibility.
So I think about introducing a new field instead and mark the old as deprecated.

[Sergey Vilgelm]

So I think about introducing a new field instead and mark the old as deprecated.

this is great

[Ernest Micklei]

@SVilgelm can you verify / comment on the PR (will create that later today)

[Sergey Vilgelm]

sure, I will check it

[Sergey Vilgelm]

I'm completely OK with the possible values, but the setters Possible and Allowable must to write into same value.
See, we have a huge project with some old legacy code, that we are not going to change anytime soon, except bug fixes.
It would be great if Allowable values will also work, without replacing them to Possible

I would recommend you to change the AllowableValues function to write into PossibleValues:

func (p *Parameter) AllowableValues(values map[string]string) *Parameter {
	allowableSortedKeys := make([]string, 0, len(values))
	for k := range values {
		allowableSortedKeys = append(allowableSortedKeys, k)
	}
	sort.Strings(allowableSortedKeys)

	p.data.PossibleValues = make([]string, 0, len(values))
	for _, k := range allowableSortedKeys {
		p.data.PossibleValues = append(p.data.PossibleValues, values[k])
	}
	return p
}

and then update go-restful-openapi to use PossibleValues:

	if numPossible := len(param.PossibleValues); numPossible > 0 {
		// init Enum to our known size and populate it
		p.Enum = make([]interface{}, 0, numPossible)
		for _, value := range param.PossibleValues {
			p.Enum = append(p.Enum, value)
		}
	}

[Ernest Micklei]

hi @SVilgelm , I agree with your suggestion to not have to change existing code.