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:
OAI/OpenAPI-Specification#1801