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

Comments

Projects
None yet
3 participants
@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

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti May 5, 2015

Owner

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?

Owner

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?

@imade

This comment has been minimized.

Show comment
Hide comment
@imade

imade 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)

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)
@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti May 5, 2015

Owner

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.

Owner

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.

@imade

This comment has been minimized.

Show comment
Hide comment
@imade

imade May 5, 2015

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

imade commented May 5, 2015

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

@bassmake

This comment has been minimized.

Show comment
Hide comment
@bassmake

bassmake May 26, 2015

Contributor

Hi, any news in this issue?

Contributor

bassmake commented May 26, 2015

Hi, any news in this issue?

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Jun 3, 2015

Owner

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

Owner

fabiomaffioletti commented Jun 3, 2015

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

@bassmake

This comment has been minimized.

Show comment
Hide comment
@bassmake

bassmake Jun 4, 2015

Contributor

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?

Contributor

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?

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Jun 5, 2015

Owner

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

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 ;)
@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Jun 11, 2015

Owner

Released with version 1.1.15

Owner

fabiomaffioletti commented Jun 11, 2015

Released with version 1.1.15

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment