Improce doc sort order

[chaikivskyi]

Problem

When a group does not have a weight defined, the sorting order becomes unpredictable.
As a result, the API documentation appears cluttered and difficult to navigate.

Solution

Introduce a secondary sorting rule:
Primary: sort by weight (when defined)
Fallback: sort by group name when weight is not set

Result

This change ensures a consistent and predictable order in the API documentation, making it cleaner, more readable, and significantly easier to find the required groups.

[romalytvynenko]

@chaikivskyi aren't endpoints sorted based on their definition order by default?

[chaikivskyi]

@romalytvynenko No, on my project, the first endpoint displayed comes from line 47 of one of the route files.
Sorting endpoints purely by definition order isn't ideal in my case.
If this behavior is useful for other devs, it may be worth adding a configuration option to allow different sorting strategies.

[chaikivskyi]

@romalytvynenko There is one more issue related to the sort order. We currently do not create root tags for paths that don’t have the #[Group] attribute, so all such routes end up at the end of the list.

I suggest also creating root tags for all routes in the documentation, even when the #[Group] attribute is missing. Please let me know if this approach makes sense to you.

[chaikivskyi]

Hi @romalytvynenko , any update?

[romalytvynenko]

@chaikivskyi I need a bit more time to review, but I definitely plan to merge it.

[romalytvynenko]

@chaikivskyi I merged but then noticed that indeed, Scramble used to sort groups (that have names) based on their definition order by default. So I reverted it as I believe that definition order allows users to manually sort endpoints groups by some logic just by moving definitions.

I understand your case but I'd rather go with additional configuration option, then changing this default.

Here is a screenshot from my demo project where you can see that groups are ordered in the order they are defined in api.php.