[Bug] Update OpenAPI spec to be compliant

[matoszz]

I discovered several inconsistencies with our OpenAPI specification when trying to upload to our new docs site, but there are likely more. I made a first pass in this PR but the spec is still non-compliant for several reasons you can see by using openAPI spec linting tool.

I personally use vacuum; you can save / see the active openapi specification by doing something similar to:

curl https://api.theopenlane.io/api-docs > api.json

and then can run a linter against the spec such as:

vacuum lint api.json -d