Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ordering of @ApiObjectField #104

Closed
imade opened this issue Apr 1, 2015 · 9 comments
Closed

Ordering of @ApiObjectField #104

imade opened this issue Apr 1, 2015 · 9 comments

Comments

@imade
Copy link

@imade imade commented Apr 1, 2015

Is there a way or workaround to specify the order of the ApiObjectFields? Problem is that if I have a following class as a POST body object:

package com.yt.mps.cmdrs.domain.sendsms;

import org.jsondoc.core.annotation.ApiObject;
import org.jsondoc.core.annotation.ApiObjectField;

@ApiObject
public class Person {

    @ApiObjectField
    private String name;

    @ApiObjectField
    private String email;

    //...
}

Then in Jsondoc UI playground the fields appear in alphabetical order:

{
  "email": "",
  "name": ""
}

This is a simplistic example, but In real world with more complex structures being able to list the fields in logical order makes the API much easier to understand for the clients.

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented May 5, 2015

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?

Loading

@imade
Copy link
Author

@imade imade commented May 5, 2015

I think we could have 2 ways:

  1. By convention - without explicitly specifying the order use the same sequence as pojo properties are defined in.
  2. Explicit - yes, something like @ApiObjectField(order = 1)

Loading

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented May 5, 2015

Number one can't be done: http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html#getDeclaredFields()

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.

Loading

@imade
Copy link
Author

@imade imade commented May 5, 2015

OK, I could live without number 1, it's more of a convenience aspect.

Loading

@bassmake
Copy link
Contributor

@bassmake bassmake commented May 26, 2015

Hi, any news in this issue?

Loading

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented Jun 3, 2015

Not yet. Don't have time at the moment. Submit a pull request if you can.

Loading

@bassmake
Copy link
Contributor

@bassmake bassmake commented Jun 4, 2015

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?

Loading

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented Jun 5, 2015

Thank you.

  • 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 ;)

Loading

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented Jun 11, 2015

Released with version 1.1.15

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants