global "consumes" flag should be ignored when method is GET or DELETE

JLLeitschuh commented 7 years ago

Description

In the Swagger UI if you have a global consumes set then all of the controllers (for example in spring) will have the consumes annotation filled in. This makes the swagger-ui not work for GET and DELETE.

You can read the discussion as to why here: https://github.com/swagger-api/swagger-ui/issues/2408

Basically it comes down to this:

Yes, you can send a request body with GET but it should not have any meaning. If you give it meaning by parsing it on the server and changing your response based on its contents, then you are ignoring this recommendation in the HTTP/1.1 spec, section 4.3:

[...] if the request method does not include defined semantics for an entity-body, then the message-body SHOULD be ignored when handling the request.

And the description of the GET method in the HTTP/1.1 spec, section 9.3:

The GET method means retrieve whatever information ([...]) is identified by the Request-URI.

- http://stackoverflow.com/a/983458/3708426

Swagger-codegen version

Latest master

Swagger declaration file content or url

swagger: '2.0'

info:
  # .... ect

consumes:
  - application/json

Command line used for generation

// Configuration using a gradle plugin in gradle script kotlin
configure<CodegenConfigurator> {
    // Much of the irrelevant configuration has been removed.
    lang = "io.swagger.codegen.languages.SpringCodegen"
    additionalProperties.apply {
        put("java8", "true")
    }
}

Steps to reproduce

Have your swagger spec declare that it consumes some mime type
Try to send a GET request with the swagger-ui inside of spring with your API being generated with spring fox.

You will get a 415 error from spring because you haven't passed the Content-Type header.

Suggest a Fix

Options:

The consumes field in the spring (and probably other) controllers should not be populated on get and delete requests.
- The consumes global field should be ignored but the one directly on the get request should be respected. Eg:
```
paths:
/cats:
get:
  consumes:
    - application/x-www-form-urlencoded
  # ....
```
- Some configuration flag should be introduced to allow you to chose to not generate consumes on GET and DELETE methods.
- An issue should be opened with the Open API specification for 3.0

wing328 commented 7 years ago

@JLLeitschuh swagger codegen (more precisely swagger parser) also supports global consumes and produces with an option to override the default (global) setting per operation.

Below is an example on how to reset the consumes to nothing (empty array):

consumes: []

Would this resolve the issue for you?

JLLeitschuh commented 7 years ago

I suppose it would. It's annoying that you need to put it on every get method.

wing328 commented 7 years ago

I would say that's the right way to do it as the spec should be the source of truth describing the REST API.

There are many tools built on top of Swagger/OpenAPI spec and I'm not aware of any implementing the logic you described as likely other tools also assume the consumes is correctly defined.

JLLeitschuh commented 7 years ago

https://github.com/OAI/OpenAPI-Specification/issues/873#issuecomment-283226193

swagger-api / swagger-codegen