Support definition of Schema property order

There has been some discussion in smallrye/smallrye-open-api#87 around ways for a user of MP-OAI to define the order of properties read during annotation/class scanning. Although maybe not technically significant for formats like JSON and YAML, predicable order does help with readability and may be significant for formats like XML.

Several annotations are in common use today by the various serialization frameworks that could be looked at for an idea of how to implement the same option in MP-OAI

• javax.json.bind.annotation.JsonbPropertyOrder
• javax.xml.bind.annotation.XmlType#propOrder
• com.fasterxml.jackson.annotation.JsonPropertyOrder

One possible option is to define a new String[] propertyOrder attribute in @Schema that behaves similarly to the three format-specific annotations listed above.

Other things to consider:

1. Ordering when inheritance is involved, should align with common behavior of existing serialization frameworks (suggestions below)
   1. Parent fields with order specified (excluding any fields that the child explicitly provides order for)
   2. Child fields with order specified
   3. Parent fields without order specified
   4. Child fields without order specified
2. Clarity around precedence of ordering. The model reader’s ordering and the static file would supersede any ordering defined in annotations
3. Potential mp.openapi configuration option to override ordering

[MikeEdgar]

What are the group’s thoughts on placing the new @Order annotation in the org.eclipse.microprofile.openapi.annotations package (rather than in media) to allow for re-use with other items (e.g. ordering of parameters or other things we haven’t though of) in the future?

[MikeEdgar]

I’m in agreement about not re-using the solution to #360. It might take some time to determine a good approach there and I think whatever solution we come up with will probably be too verbose for here.