Separate description per allowableValue

[cowwoc]

It's not clear how to document enums in a scalable manner. I want to provide users with a list of all possible enum values, and for each value provide a description of its meaning.

Ideally, I would like to link to the enum from the REST method that returns it and then provide a separate description (annotation) per value.

@ApiModelProperty(dataType = "string", allowableValues = "Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday", value = "description", notes = "notes") is not a good fit because:

1. The documentation falls out of date if an enum value is added or removed.
2. I am forced to dump the description for all values in a single notes field. This clutters the code and is hard to maintain.

Any ideas?

[webron]

The spec doesn't really provide a way to give a description per enum value. Without going too much into details, that's pretty much a limitation of JSON Schema. The only way to provide such a documentation would be via the notes field. As for the values of the enum, if the type of the property is an enum on its own, the enum should be parsed automatically to enum values and you should not need to declare those manually (so no need to maintain the list).

[cowwoc]

@webron Is this a limitation of the Swagger schema? Or the limitation of the JSON protocol?

[webron]

Not JSON protocol but JSON Schema. It's a bit of a limitation of both. JSON Schema doesn't allow it, and we didn't provide an alternative solution in the spec.

[webron]

@cowwoc - don't think we can do much more here.

[cowwoc]

@webron Okay, please provide an alternative solution in the spec as you mentioned (change this issue to a feature request).

[webron]

You can open an issue on swagger-spec with a detailed request if you'd like it to be considered for a future version of the spec.

For now, you'd have to document it manually in the notes field

[cowwoc]

Done. Closing this issue.