Improve OpenAPI documentation #2609
Description
Areas for improvement
- not all return codes are documented (actually just a few)
- Are the listed return coded upfront still helpful (in combination with the bullet point above)
- Sometimes the HATEOAS links look weird in the docs and blow the examples up.
- make required values more visible