Allows to define the order of the operations on the summary pages and sidenav.

[sergeymisura]

I started using Dapperdox for our project and quickly ran into the same issue as described in the #52. Here are the changes I have made to the spec parser for our own usage, in case you find them helpful:

• The parser sorts methods within a group alphabetically by default
• It allows to specify 'x-sortOrder' extension in the operation object to define the sorting order manually
• Operations without 'x-sortOrder' will be below those that have it

[zxchris]

Thanks for the PR. We'll review as soon!

[zxchris]

This doesn't work as expected if you don't define x-navigateMethodsByName: true (or set it to false), as the entries are still ordered by Summary, it it probably should be ordered by operationName (I tried this out on the standard petstore example which isn't really REST, but was good enough to see the issue).

See next comment though....

[zxchris]

I've commented the code around the use of o.Summary as the default sort order, because this does not work (we feel) as expected if x-navigateMethodsByName is in force.

So, this has got us thinking about sorting in general. It might be useful to be able to sort by one of the following:

1. Summary (as you have defined by default)
2. Operation name (GET, POST etc by default, or x-operationName if defined)
3. Path

So, we could potentially have an global x-sortBy and have that take fixed values such as summary, operation or path (or perhaps a comma separated list so that you can order by path, and then method in the path for example).

Or we add a x-sortOrder parameter as you have, where specification writers can provide values to control the order of methods in the presentation, in the same way that we order guides. This would have to be given for every method.

We currently like the x-sortBy option, as it seems quite flexible and does not require the spec writer to supply and manage additional information on each method. It doesn't offer the fine control that x-SortOrder would, but will that fine grain of control be needed?

How does that sound to you?