Swagger-ui: Message "DELETE operations cannot have a requestBody" appears on a previously OK specification.

[mikefidel]

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.

[mikefidel]

I should have added that there isn't an urgency to upgrade Swagger-UI beyond 3.13.0. I've been doing it only to keep our production and testing systems reasonably current with bug fixes and security patches (if any).

[webron]

@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 type: long for a schema.

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.

[mikefidel]

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.

[mikefidel]

Contacted SmartBear Customer Care.
The following identifier was assigned to the submission: 00290297.

[ErKiran]

@mikefidel I still got same Error message DELETE operations cannot have a requestBody. Was it bug or upgrade. Do SmartBear patch it? How you solve this issue?

[mikefidel]

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.

[erunion]

Also seeing this error, and it seems like since it's just a semantic and not a schema error, that the spec is still okay.

Still, kind of annoying that the error is present to begin with on a valid usecase.

[javabrett]

This type of operation (DELETE, GET requests with a body) was explicitly banned in Open API 3.0. Prior to that it was allowed or vague.

[erunion]

https://tools.ietf.org/html/rfc7231#section-4.3.5

A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.

So it is...

[javabrett]

I think the important 3.0 spec clause is: https://swagger.io/specification/#operationRequestBody

[Arekusei]

https://tools.ietf.org/html/rfc7231#section-4.3.5

A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.

So it is...

But it doesn't mean that body is disallowed.
https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE

Request has body | May

And AWS API Gateway allows this.

[javabrett]

But it doesn't mean that body is disallowed.

I think it does for DELETE operations as far as OpenAPI 3.x specification applications go.

[shockey]

@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:

The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.

[adjenks]

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

[KamranShahid]

This is an open issue and shouldn't be closed till the support is available properly

[n2ygk]

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"?

[markwalker42]

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.

[jmini]

According to the PR pending in the OpenAPI Spec repository: https://github.com/OAI/OpenAPI-Specification/pull/1937, requestBody will be allowed for DELETE operations.

IMO this issue can be reopened and implemented.

[SandorUK]

Any update on this one? I'm working with https://app.swaggerhub.com using OAS 3.0 and this doesn't seem to be supported yet.

[shockey]

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.

[Rahtgaz]

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.

[ntloi95]

@Rahtgaz, GET method does not have request body, man.

[adjenks]

@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.

[fisx]

According to the PR pending in the OpenAPI Spec repository: OAI/OpenAPI-Specification#1937, requestBody will be allowed for DELETE operations.

IMO this issue can be reopened and implemented.

This PR is merged by now. Could you please reconsider re-opening this issue?

[n2ygk]

@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.

[fisx]

cool, thanks for the clarification.

[benktesh]

I am also expectig to use requestBody on Delete operations specially to pass multiple identifiers for deletion. I am new to swagger-ui. I would appreciate if someone can point me to a resource (if exists) where I can see swagger-ui updates and or plans.

[ffflorian]

Any update on this? @n2ygk

[n2ygk]

@ffflorian it's been merged into 3.1.0 which is not yet released.

[ffflorian]

Thanks for the update @n2ygk :slightly_smiling_face: