Request with GET/HEAD method cannot have body

[pinoy4]

I am opening this issue to address this problem.
It has already been reported in issue #2136 but that issue is closed.
From what I understand it has been closed by @fehguy stating:

Body payloads are not supported by swagger in a GET operation, and is typically not supported by any server frameworks, even though the http specification is vague about supporting them.

If I am seeing the bigger picture here this statement refers to RFC 2616, section 4.3 which was the standard until June 2014 when it was superseded by RFC 7230, section 3.3 and RFC 7231, section 4.3.1.
This has already been mentioned in the previous issue (#2136) by @ehartford but no response was given.

I am aware that the use of a body in a GET request still should be limited when designing endpoints but it should definitely NOT be prohibited. I would like to understand what the reasoning behind explicitly prohibiting this is as @webron said (again in #2136):

tbh, I don't see that happening. In 3.0, we have explicitly expressed that payloads with not work for GET, DELETE and such.

Please understand that this decision is very limiting to some of us as we are forced to choose between implementing our APIs differently from what we believe is the best way and using swagger to document it (and enable the "Try it out" feature).

Thank you very much for your time,
Francesco

[webron]

@pinoy4 - we understand the pain that this may cause for some API designs, however this is not going to change. We cannot go out of bounds of what the spec allows, and it does not allow it. There are other features that people wish existed, and when they don't they can't describe their APIs using Swagger/OpenAPI. However, we will never get to the point where we cover 100% of API designs.

[ehartford]

The spec does not forbid this. I have confirmed this interpretation with the committee if you check the mailing list.

…

On Apr 6, 2017 9:58 AM, "Ron" ***@***.***> wrote: @pinoy4 <https://github.com/pinoy4> - we understand the pain that this may cause for some API designs, however this is not going to change. We cannot go out of bounds of what the spec allows, and it does not allow it. There are other features that people wish existed, and when they don't they can't describe their APIs using Swagger/OpenAPI. However, we will never get to the point where we cover 100% of API designs. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2867 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABEOBbCpgQdvlU_3ot-R_wrx8narV9DZks5rtRmrgaJpZM4M1SO-> .

[webron]

The Swagger/OpenAPI spec forbids this.

[webron]

@ehartford regardless, if you want to point me to the post in the mailing list bringing it up, I can raise it as a concern with the OpenAPI spec.

[pinoy4]

@webron I know your goal is not to support 100% possible cases, especially since the OpenAPI spec doesn't have this goal (and I agree it should not be it's goal).
As @ehartford stated I also thought that the OpenAPI spec did not forbid this as I couldn't find it mentioned anywhere in the docs.
If you have the time to point me to it I would greatly appreciate it. Please don't see this as me not wanting to look hard enough, I really couldn't find it.

[webron]

Version 2.0 wasn't clear about it, but for the moment, 3.0 is.

From the Operation Object:

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

This is not a decision we can simply flip here in the project. FWIW, out of the votes, I was the only one opposed to the change, and we go with majority (as we should). This is why I've asked @ehartford for a reference to the mailing list, as that information may be enough to turn the decision (it's technically not too late). However, as long as the decision remains, we will not support it in Swagger-UI.

[pinoy4]

Thank's for the link. I didn't give enough attention to that table, my bad.
Well, that's it, you told me all I needed to know. Have a good one and thank's again.