Define best practices for defining api docs centrally

[woylie]

Currently, all the api doc macros are meant to be used within the controllers. It might be better if some definitions (i.e. shared parameters, warnings etc.) would be defined in a central place. Also, sometimes it might be a better idea to define the route descriptions in a central place as well. We should define best practices for this and figure out how to handle centrally defined api macros.

[woylie]

See also this comment and fork.