switch to OpenAPI 3.0

[joker234]

Currently, we are using OpenAPI 2.0 (aka Swagger) to define our API. The newer version OpenAPI 3.0 is released for almost 4 years now, at some point we should consider switching to the newer API definition structure. This issue is meant as reminder and open for discussions and remarks on that topic.

[bonaparten]

I am wondering whether Swagger is the way to go for the future. It gives us an out-of-the-box UI with little code effort, but I still think our page is not user-friendly. It has too many navigation menus, repeated parameters and repeated descriptions. Scrolling to the right endpoint and then to the execute button is not immediate. If it is possible to set up Swagger making the UI clean I am for it. Otherwise, I think we should consider something different (html and js?).

[tyrasd]

ok, there are two issues potentially at play here: one is the definition in the OpenAPI "swagger" JSON, and the second is the user interface. Of course when one upgrades the definitions, one also needs to update the swagger user interface, but that's not what @joker234 mainly proposed here.

I think that updating the definition standard to 3.0 would be fine (and perhaps not even to be seen as breaking when considering that we nowhere really documented that the current swagger json is supposed to be our official api specs). But the question is how easy it is to upgrade, given that this is generated by spring for us. Probably it requires upgrading to a newer version of spring as well?!

[TheGreatRefrigerator]

This was done in ORS some time ago. Check for related changes:
GIScience/openrouteservice#1380
GIScience/openrouteservice#1487