swagger tweaks: reordering and remove deprecated parameters

[tyrasd]

Description

A few changes to the swagger api playground:

• reorder "tags" in specs:
  • for aggregation resources: count first, then length, area and perimeter, then users and last contributions
  • for data extraction: geometry, then elementsFullHistory/geometry, then contributions/geometry
  • no change for metadata 😉
  • reasoning: alphabetical sorting is not the most user friendly, IMHO. I propose the following sorting: simpler, more often used resources should come first, and more complex ones later
• start phasing out deprecated types/keys/values parameters by not offering them in swagger anymore
  • reasoning: a) it makes it more evident that these parameters should not be used, b) we already have a few endpoint which do not support these old deprecated filters (e.g. all contributions endpoints), yet swagger still shows them as apparently valid options.
• make time parameter for contribution endpoint optional (fall back to full time range if not specified??) TODO: check if this is a good idea and if it even works as intended

Checklist

• My code follows the code-style rules, and I have checked on the static analyses
• I have commented my code
• I have written javadoc (required for public methods)
• I have added sufficient unit and API tests
• I have made corresponding changes to the documentation
• I have updated the CHANGELOG.md
• I have adjusted the examples in the check-ohsome-api script or created an issue in the corresponding repository. More Information here.

[FabiKo117]

I agree with both points: bringing a specific ordering in the speccs and further removing the deprecated types, keys, values parameters. This also reduces the code further.

What just came into my mind: Would it make sense to include a specific message (e.g. in a dedicated JSON field) in the response if the user used a deprecated parameter, endpoint, whatever to get this response and that he/she should check the docs and update this, as this specific request won't work anymore after the next major release? To better display this, we could add a specific section in the docs explaining which parameters, endpoints, etc. were deprecated in which version and from when they won't be available anymore.

[tyrasd]

Would it make sense to include a specific message (e.g. in a dedicated JSON field) in the response if the user used a deprecated parameter, endpoint, whatever to get this response and that he/she should check the docs and update this, as this specific request won't work anymore after the next major release?

That sounds like a good idea! 👍 At least for the JSON (aggregation) output format this should be possible without a problem. I'm not 100% sure about csv (maybe including it in the header comment would work?) and GeoJSON, though.