Swagger spec warning about request-baskets

[darklynx]

how did you get this warning / error message?
neither swagger-codegen nor js-yaml did not complain about YAML ...

can you also explain the reasons behind this error?

[darklynx]

probably moving the description property into Headers definition object should be sufficient and will actually solve the warning, am I right?

according to this comment: swagger-api/swagger-js#402 (comment) if there is $ref there should be nothing else

[IvanGoncharov]

how did you get this warning / error message?

I use Sway: https://github.com/apigee-127/sway/tree/master/docs#semantic-validation
But it has multiple problems including problems with release cycle.
So we started working on our own tool: https://github.com/APIs-guru/OpenAPI-Lint

according to this comment: swagger-api/swagger-js#402 (comment) if there is $ref there should be nothing else

It can be anything but it's should be overridden during resolution.

probably moving the description property into Headers definition object should be sufficient and will actually solve the warning, am I right?

Yes. Generic solution is allOf wrapper but in you case but your custom solution is better 👍