Add content-type metadata to operations

[pose]

As a swagger user, I would like to specify which content-type will be returned in the response. For instance, the user may choose application/json to receive JSON or it can switch to text/xml in order to get XML in the response. In order to do this, it should be great to provide a field in the model to indicate the supported mime-types.

One possible way to do this is to attach to each operation the supported content types. Take for instance the following operations array:

 {
    "path": "/user.{format}",
    "description": "Operations about user",
    "operations": [{
        "httpMethod": "POST",
        "summary": "Create user",
        "notes": "This can only be done by the logged in user.",
        "responseClass": "void",
        "nickname": "createUser",
        "parameters": [{
            "description": "Created user object",
            "paramType": "body",
            "required": true,
            "allowMultiple": false,
            "dataType": "User"
        }]
    }]
}

We can add a new field supportedContentTypes where the supported content-types are listed. In this case, application/json and text/xml are the supported ones:

 {
    "path": "/user.{format}",
    "description": "Operations about user",
    "operations": [{
        "httpMethod": "POST",
        "summary": "Create user",
        "notes": "This can only be done by the logged in user.",
        "responseClass": "void",
        "nickname": "createUser",
        "supportedContentTypes": ["application/json", "text/xml"],
        "parameters": [{
            "description": "Created user object",
            "paramType": "body",
            "required": true,
            "allowMultiple": false,
            "dataType": "User"
        }]
    }]
}

Going one step further, assuming that this proposal is accepted, in swagger-ui this should be represented using a list with the valid mime-types values where the user can pick the one he wants to use.

Thoughts? Comments?
Thanks in advance,

[3miliano]

There are two different kind of content types. One for the body of the POST/PUT request, and one that is the actual response format of a GET request.

For POST/PUT the user should be able to select the Content-Type of the body just like it selects the actual content of the UI or any other parameter.

In the GET case, what needs to be sent is the Accept header which denotes which content the client is willing to accept. Ideally the API should format its response to that requested or reply with an error code is no format can be negotiated.

In any case this should be considered an alternative to those using

/uri1/uri2.{format}

Regarding the field name, "content-type" is not a good name. Better to follow the camel case notation of other fields.

[fehguy]

This has been added to the roadmap (https://github.com/wordnik/swagger-core/wiki/Specification-Roadmap), the propsed terms are accepts (receives) and produces (creates).

[miketzian]

Hey all, what's the status on this ?

Interestingly, the supportedContentTypes option is already supported by the swagger.js backbone library :260 :

op = new SwaggerOperation(o.nickname, resource_path, o.httpMethod, o.parameters, o.summary, o.notes, o.responseClass, o.errorResponses, this, o.supportedContentTypes);

And seems to be implemented on the swagger-ui side as well.

I suppose you're leaning away from using Produces/Consumes on the methods as the wordnik way seems to be to define those on resources which extend a base resource. Right?

You'd almost think that overall resource annotations should work as-is (certainly what I'd expected) though obviously the code just doesn't do it right now.

If this should pull from the class level and perhaps in the future from the method level, happy to do an implementation for same? Otherwise I think I'll end up forking the ui and imposing it but I don't think that's ideal by any stretch.

-Mike

[fehguy]

Our goal is to make the spec declarative the right way, then make the implementation follow accordingly. I do believe "produces" and "consumes" is the right naming convention. I also would like to see an override mechanism from the top level (server) to each resource, then method. I hope to get this in shortly, like this month.

[fehguy]

Take a look here for how we'd like to support this:

https://github.com/wordnik/swagger-core/blob/1.2.0-spec/samples/scala-jaxrs-fileupload/src/main/scala/com/wordnik/swagger/sample/resource/PetResource.scala#L58

This is a language-specific example, but in general, would like to have the following in the spec:

[
  {
    "httpMethod": "POST",
    "summary": "uploads a form data",
    "responseClass": "void",
    "nickname": "formData",
    "consumes": [
      "application/json"
    ],
    "produces": [
      "application/json"
    ],
...

[fehguy]

added to 1.3.0-SNAPSHOT, and will be updated in the documentation on the wiki shortly after release of swagger-core-1.3.0.