This could be an interesting improvement. The only way I can think of to implement it is to add an additional property "order" to the ApiObjectField annotation or another annotation "ApiOrder" to be placed on the field and use the value in a comparator. What do you think?
Returns an array of Field objects reflecting all the fields declared by the class or interface represented by this Class object. This includes public, protected, default (package) access, and private fields, but excludes inherited fields. The elements in the array returned are not sorted and are not in any particular order.
I started to work on this.
Do you think that ApiObjectFieldDoc.order should be int or Integer? (-1 or null in comparator as MAX value)
Also I think that fields with no order should be generated after fields with order. Agree?
I found JSONDocTemplateBuilder.build that returns Map<String, Object>. I think that here should be something that can remember sorted fields. Maybe new class JSONDocTemplate?
should be Integer. I would say that -1 (-2, -3, negative values in general) needs to be considered as a valid value, so a field annotated with order = -1 needs to be shown before the one annotated with order = 0. This would give more flexibility. Default value for the order property should be Integer.MAX, so that in the comparator it will be considered as the last in the list.
a new class JSONDocTemplate could be fine, but if you find that it's not easy to convert the Map to a class, then to keep the field order you should consider having a more convenient Map implementation like LinkedHashMap or TreeMap.
What do you think? Please remember to add unit tests ;)