Improve REST API docs

[lastalfriday]

https://github.com/openmobilityfoundation/mobility-data-specification/blob/2.0.0-rc1/agency/README.md#vehicles

You should consider making the docs a bit more clear here.
What we actually have on /vehicles is 3 endpoints

1. GET /vehicles
2. GET /vehicles/{vehicle uuid}
3. POST /vehicles

• 1 and 2 should each have a seperate doc point.
• 1 and 2 should be GET and not really POST endpoints?
• 1 returns an array and 2 returns an object? This is unclear from the docs
• 3 should strickly return 201 status code

This might also count for other places, I just started implementing the 2.0 specs, and I seem to recall these confusing things when implementing 1.0 as well

[thekaveman]

This will all be described in OpenAPI 3.1 -- See #832 and openmobilityfoundation/mds-openapi for more details.

[lastalfriday]

Ah, right, much better. Thank you