Make server Endpoints methods return arrays instead of maps

[jprobinson]

Maps do not allow users to declare the order in which their endpoints are registered against our routers, which can force developers to compromise how their URIs are constructed or even force users to build custom router implementations.

By switching to an array, users will be allowed to declare the order in which routes will be registered. Long term goal here is to eventually open up a path for us to remove any custom routing options in the future and purely rely on gorilla/mux.

I haven't figured out exactly what this API will look like, but I hope the change to be simple enough that minimal refactoring is required for the upgrade.

[marwan-at-work]

Why not just let the user provide the ServerMux?

[jprobinson]

The kit server allows folks to provide their own custom mux, but I think that may be tossing the problem over the fence at the user. They'd still have to selectively iterate over the map in the order they choose.

I do like that the current implementation encourages users to provide all the routes encapsulated in a single data structure, which is why I was considering an array/slice here, but perhaps a different paradigm may serve us better?

Any thoughts on what the API would look like?

[marwan-at-work]

@jprobinson I opened a separate issue for passing the Mux directly (#195) which we can discuss how to do that over there.

However, if we want to still have "our own way" of declaring the Routes -> Handlers data structure, then the only reason I see a benefit for this, is that we should do it in a way that we can generate an OpenAPI V3 Spec..this would be a huge win IMO: a user just declares routes in pure Go, and not only do they get working handlers, they get automatic spec and UI documentation.