Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify when consumes/produces take effect #581

Closed
ePaul opened this issue Feb 28, 2016 · 6 comments
Closed

Clarify when consumes/produces take effect #581

ePaul opened this issue Feb 28, 2016 · 6 comments

Comments

@ePaul
Copy link
Contributor

ePaul commented Feb 28, 2016

The 2.0 specification has the top-level consumes and produces properties, as well as for each operation.

When the operation is one whose HTTP method's definition doesn't include a payload semantic (most prominently GET, but also HEAD and DELETE, maybe OPTIONS), there is no point in saying the operation "consumes" anything (and there is no point in sending a Content-Type header when there is no body.)

On the operation level thus "consumes" should be forbidden for such operations, and the top-level "consumes" property should be declared in the description to not apply for such operations.

This was triggered by Issue swagger-api/swagger-codegen#2254.

@ePaul ePaul changed the title Make it clear that GET/HEAD requests don't consume anything. Make it clear that GET requests don't consume anything. Feb 28, 2016
@jjqq2013
Copy link

+1

@webron
Copy link
Member

webron commented Mar 1, 2016

Not getting into the argument of whether it makes sense to send a payload to a GET but at the end of the day, the HTTP spec does not explicitly prohibits sending a payload with GET operations, and the fact is that some APIs do that. Saying that GET requests don't consume anything is not always true (and also DELETE, HEAD and OPTIONS).

As for the codegen, as long as there's no body parameter, the consumes value is meaningless, regardless of which HTTP verb is used (including POST, PUT), and that should be the guiding line.

@ePaul
Copy link
Contributor Author

ePaul commented Mar 1, 2016

@webron The guideline "consumes only applies where there is a body parameter" (and maybe in extension also "produces only applies for responses with a schema") sounds good. My proposal is to include an explicit mention of this in the next version of the specification.

@webron webron changed the title Make it clear that GET requests don't consume anything. Clarify when consumes/produces take effect Mar 1, 2016
@webron
Copy link
Member

webron commented Mar 1, 2016

Sure thing, that makes perfect sense, and the part about produces is accurate as well. I've changed the title to reflect the intent here. Note that this is just a clarification and not a change in behavior really - I'd expect existing tools to behave that way with the current version as well, including the codegen.

@webron
Copy link
Member

webron commented Mar 1, 2016

Parent issues: #589, #560

@webron
Copy link
Member

webron commented Mar 3, 2017

Well, both consumes and produces have been removed and replaced by better mechanisms for their respective representations.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants