swagger-ui: Message "DELETE operations cannot have a requestBody" appears on a previously OK specification.
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
| Q | A |
|---|---|
| Bug or feature request? | Bug |
| Which Swagger/OpenAPI version? | 3.0 |
| Which Swagger-UI version? | current SwaggerHub version |
| How did you install Swagger-UI? | problem does not occur in v3.13.0 which is used for testing |
| Which browser & version? | Chrome latest |
| Which operating system? | Windows 10 |
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"
Expected Behavior
No error message appears.
Current Behavior
Error message appears.
Possible Solution
Not upgrading to Swagger-UI releases after 3,13,0.
Context
As the error does not appear on our older 3.13.0 test system, we’ll not be upgrading to later versions.
About this issue
- Original URL
- State: closed
- Created 6 years ago
- Reactions: 12
- Comments: 36 (11 by maintainers)
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: https://github.com/OAI/OpenAPI-Specification/issues/1801
I just ran into the same issue, it seems like 3.1.0 has been released. Are there any plans to update swagger-ui to support that?
This is an open issue and shouldn’t be closed till the support is available properly
But it doesn’t mean that body is disallowed. https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE
And AWS API Gateway allows this.
Can this be re-opened? I find these “errors” rather annoying when validating openapi schemas in swagger-ui. I think the errors should be removed when spec version is for 3.1.0, ideally also for 3.0.x imho.
This also affects GET operations. Not just DELETE. We use a body payload for LDAP authentication on a CRUD API for active directory domain services.
@fisx That merge into 3.0 was reverted as the group considered this to be too big a change and pushed it to 3.1. See https://github.com/OAI/OpenAPI-Specification/pull/2117
So this change has been acccepted but is pending 3.1 release: https://github.com/OAI/OpenAPI-Specification/issues/2025
So, for forward planning purposes, this is an approved change for 3.1 and swagger-ui should support it.
According to the PR pending in the OpenAPI Spec repository: https://github.com/OAI/OpenAPI-Specification/pull/1937,
requestBodywill be allowed for DELETE operations.IMO this issue can be reopened and implemented.
I just pulled the latest docker image and the message still appears.
I too am running up against this issue and it’s good to know that the error doesn’t necessarily get in the way but I have to disagree with the statement that the OpenAPI specifically disallows bodies in HTTP methods that don’t have specific semantics defined for them.
My read is that if a body is provided for such methods like DELETE then the consumers (e.g. tools) shall ignore it. So I would think that the proper response for a tool like SwaggerEditor would be to mark the requestBody as ignored (or literally ignore it altogether) in that case rather than indicate an error.
@ntloi95 The specs say it has ‘no defined semantics’, but doesn’t explicitly prohibit it. It is defined the exact same way for DELETE, which is why this ticket is open.
I don’t think it’s a great idea to put a body in a GET request, but I wouldn’t say it “does not have a request body, man”, his has one.
@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:
@ABSAhmad bro,has the problem been solved?
No update, as there’s nothing to do in Swagger UI right now — the OAI has not yet merged their change to the spec that @jmini mentioned.
Once a change is released, we’ll be able to support it.
interestingly, despite the error message, the delete operation with a requestBody still works as expected. Perhaps an option for me to say “I know that my API requires DELETE with a requestBody”?
I think the important 3.0 spec clause is: https://swagger.io/specification/#operationRequestBody
This type of operation (
DELETE,GETrequests with a body) was explicitly banned in Open API 3.0. Prior to that it was allowed or vague.