#1171 fix validity issues in openapi/swagger spec files

Closes #1171 (closed)

Reworked some parts of the openapi files to make it valid and allow code generation using https://github.com/swagger-api/swagger-codegen