Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Message "DELETE operations cannot have a requestBody" appears on a previously OK specification. #4425
On 2018/04/08, the v3.0 specification I had worked was not shown as having errors in SwaggerHub. The following morning, 2018/04/09, immediately upon opening the specification the error message appeared saying "DELETE operations cannot have a requestBody".
The API I was working indeed is a DELETE method having a request payload. So the error message is correct. However, several servers accept a payload with a delete method, and on the previous months this API was being documented using SwaggerHub, no such error message was displayed.
So I am wondering if SwaggerHub was updated sometime between Sunday afternoon PST on 4/8 and Monday morning PST on 4/9. And if so, is there a conscious attempt to more rigorously enforce a standard that doesn't permit a payload to accompany a DELETE request?
I've cross checked yesterday's work by copying the last commit I made into the SwaggerHub editor. The error message appears, while at the same time yesterday's work shows up fine on my testing server. Thus I am sure I did not introduce a change to the API file in SwaggerHub after finishing yesterday.
I created a smaller API specification on SwaggerHub that demonstrates the error I am seeing. https://app.swaggerhub.com/apis/mikefidel/BUG-Delete-Method-Having-RequestBody/1.0.0
Demonstration API definition
Found at SwaggerHub https://app.swaggerhub.com/apis/mikefidel/BUG-Delete-Method-Having-RequestBody/1.0.0)
openapi: 3.0.0 info: version: '1.0.0' title: 'Bug-Delete-Method-Has-RequestBody' description: "On 2018/04/08 SwaggerHub considered this acceptable. Today (2018/04/09) an error message is displayed saying DELETE operations cannot have a requestBody." servers: - url: http://test.ndexbio.org/v2 description: "NDEx test server" paths: /networkset/members: delete: summary: Delete Networks from Network Set requestBody: content: application/json: schema: type: array description: "List of networks belonging to this network set" items: type: string format: uuid description: "Network object UUID" example: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" responses: 500-response: description: "Sloppy cut-paste - ignore this response"
No error message appears.
Error message appears.
Not upgrading to Swagger-UI releases after 3,13,0.
As the error does not appear on our older 3.13.0 test system, we'll not be upgrading to later versions.
@mikefidel Generally speaking, for issues that are related to SwaggerHub, I would ask that you contact their support through the available channels. The reason being that while their versions depend on the open source, they have their own customization of it and their own deployment schedule - and they'd be able to provide better details about such changes.
The change you're seeing is not in swagger-ui but swagger-editor. Swagger-UI will not show those errors. In swagger-editor, we've recently introduced semantic validation of OAS3 definitions, meaning the validation is more accurate and checks for more compliance with the spec itself. The spec, indeed, does not allow for payloads for DELETE (or GET and so on) operations, so you'll get such errors. There's no way to suppress those errors because they are not different than trying to use
As far as I know, the SwaggerHub team did make a deployment earlier today, and based on what you describe, it sounds like they updated to the version of swagger-editor that contains the semantic validation. I can check with them directly, and get back to you later on if it's important.
That's good to know. I'll report this through the SwaggerHub support channel myself. No need for you to get involved further.
Is going to get interesting if semantic validation will be enforced without the option to override it. Personally speaking, I'd prefer to have it if the API were brand new. But in cases where an API already exists and there are v3 features I wish to use when augmenting the existing API, that's a definite show-stopper, IMHO.
Thanks for the input.
I recall being told, according to the formal Open API Specification, Delete operations do not have request body. In my situation, the specification did not exist when the code I worked on was originally written. The development group responsible for the code base do not want to change the it just because a specification says otherwise.
The produce manager I spoke to was not keen to ignore or override the formal specification. In response my thought was to have a switch that overrode error notifications involving deviations from the Open API Specification. I would have been even satisfied with the parser issuing a "warning" instead of an "error" in such cases,
I've found that SmartBear has been proactive in continual product bug fixing and improvements, so I didn't want to push the point with him. Besides, I found I could ignore the pesky error message because the generated JSON code works fine in Swagger-UI in spite of the alarming error message.
I expect as more and more users adopt the Open API Specification and SmartBear tools, SmartBear will become tired of dealing with such legacy code issues. That... or some large paying customer will insist on something such as I proposed.
I think the important 3.0 spec clause is: https://swagger.io/specification/#operationRequestBody
But it doesn't mean that body is disallowed.
And AWS API Gateway allows this.
@javabrett is correct
HTTP itself leaves the door open to DELETE bodies, but doesn't give them semantics in the way that (for example) POST and PUT bodies have.
OpenAPI, for its part, specifically disallows bodies in HTTP methods that don't have specific semantics defined for them:
My API has a request body for a DELETE operation and I believe the design is logical and useful and do not want to be constrained by the fact that there is no "explicitly defined semantics" for the DELETE request body. I would like this to be supported. This would have to start with the OpenAPI specification though, so I have opened a ticket there: