API spec needs to be human readable and more verbose

[xinaxu]

### Tasks
- [ ] Update openapi.yml to use more accurate description and examples (e.g. what it means by returning empty array in deal status, what each status means)
- [ ] Create an openAPI playground