Fix apiGroup sorting (#1042)

[esaracco]

No description provided.

[esaracco]

@NicolasCARPi This first push fixes the sort in case order contains apiGroup. However, there is still a issue when it contains only apiName. I am on it.

[esaracco]

@NicolasCARPi I may be wrong, but I see a difficulty related to the fact that we can mix api-names and api-groups in the order section. What should be the priority to give to each other? Wouldn't it be relevant to create two dedicated order sections? One for api-groups and the other for api-names? What was the primary purpose of this section?

[esaracco]

@NicolasCARPi For instance, my PR succeeds in sorting with the following configurations:

 "order": [
    "01 - Setup",
    "setup.findOne",
    "setup.update",

    "02 - Accounts",
    "accounts.findAll",
    "accounts.findOne",
    "accounts.create",
    "accounts.delete",
    "accounts.update",

    "99 - Misc",
    "misc.findAllSomething",
    "misc.findAllSomethingElse",
    "misc.deleteSomething",
    "misc.changeSomething"
]

or even:

 "order": [
    "01 - Setup",
    "02 - Accounts",
    "99 - Misc",

    "setup.findOne",
    "setup.update",

    "accounts.findAll",
    "accounts.findOne",
    "accounts.create",
    "accounts.delete",
    "accounts.update",

    "misc.findAllSomething",
    "misc.findAllSomethingElse",
    "misc.deleteSomething",
    "misc.changeSomething"
]

This way, both api-groups and api-names are correctly sorted.
In either case, you need to explicitly specify the order of the api-groups.
Is this behaviour OK for you?

[NicolasCARPi]

I see a difficulty related to the fact that we can mix api-names and api-groups in the order section.

Yes I see it too!

What should be the priority to give to each other?

¯\_(ツ)_/¯

Wouldn't it be relevant to create two dedicated order sections? One for api-groups and the other for api-names?

That was also what I thought.

What was the primary purpose of this section?

Allow ordering of components of course! If your code does what you say it does, I think it's very good already and we don't need to have two ordering keys.

[pilotkid]

It worked for me.

 "order": [
    "setup.findOne",
    "setup.update",

    "accounts.findAll",
    "accounts.findOne",
    "accounts.create",
    "accounts.delete",
    "accounts.update",

    "misc.findAllSomething",
    "misc.findAllSomethingElse",
    "misc.deleteSomething",
    "misc.changeSomething",

    "01 - Setup",
    "02 - Accounts",
    "99 - Misc"
]

If I may chime in to the discussion about the ordering field. I did find it very confusing when I first started using apidoc on how to sort the groups and the calls themselves.

Personally how I feel it should be structured is having order become an object, with sub-objects with the keys being the groups and the value being an array in the order in which to sort.

 "order": {
    "01 - Setup": [
        "setup.findOne",
        "setup.update",
     ],

    "02 - Accounts":[
        "accounts.findAll",
        "accounts.findOne",
        "accounts.create",
        "accounts.delete",
        "accounts.update",
    ],

    "99 - Misc":[
        "misc.findAllSomething",
        "misc.findAllSomethingElse",
        "misc.deleteSomething",
        "misc.changeSomething",
    ]
}

This would also allow for backward compatibility. You would just have to check to see if the order is an object or an array.

I would be happy to see if I can accomplish this if I get the green light from @NicolasCARPi

[NicolasCARPi]

@pilotkid Yes, what you suggest looks like a good idea to me!