Support alternate media types

[kmcgain]

Currently a response example always uses the media type application/json. It would be useful to be able to specify alternate media types such as application/hal+json. The SwaggerResponseExampleAttribute could accept a content type parameter.

Happy to create a PR.

[mattfrear]

Hello

I have had this request in the past, usually for XML support. I've never heard of hal+json.

I don't really know what support Swashbuckle has for other content types. The swagger examples page here doesn't have an example of an XML example in a swagger.json file. That's a mouthful.
https://swagger.io/docs/specification/2-0/adding-examples/

This spec here is more useful:

The name of the property MUST be one of the Operation produces values (either implicit or inherited). The value SHOULD be an example of what such a response would look like.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#exampleObject

My best guess for the XML content type, is that it should look something like this:

"responses": {
    "200": {
        "description": "Success",
        "schema": {
            "$ref": "#/definitions/Blah"
        },
        "examples": {
            "application/json": {
                "id": "38",
                "title": "T-Shirt"
            },
            "text/xml": {
                "example": "<id>38</id><title>T-Shirt</title>"
            }
        }
    },

That's a complete guess though!

Again, I have no idea how Swashbuckle handles different content types, I've never had to do that. The key point from the quote above is that the content type needs to be one of the "produces" values.

My thoughts on how to implement this. I don't think the SwaggerResponseExampleAttribute should be changed as you suggested.
I think the ExamplesOperationFilter.cs should be modified to loop through each content type in the produces array, and attempt to generate examples for each one, using the appropriate serializer. So for the JSON produces, it would use Newtonsoft's JsonSerializer to generate the example. For the XML produces, it would use an XML serializer. It would find your hal+json and either use the standard JsonSerializer or a custom one written by you.

I would certainly welcome a PR that added support for other media types, starting with XML. You could include your hal+json support as part of that.

But if you just want hal+json, well I'm not seeing a lot of demand for that from the community. It might be easiest if you take a copy of ExamplesOperationFilter and customize it for your hal+json needs for now?

[freeranger]

+1 for hal+json support!

[mattfrear]

I still haven't really gotten my head around hal+json as I've never used it on a project, so I am not going to implement support for it.

FWIW I've added XML support in my feature/swashbuckle5 branch, using the method I wrote above. The code looks like this:

            foreach (var content in operation.RequestBody.Content)
            {
                content.Value.Example = content.Key.Contains("xml") ? xmlExample : jsonExample;
            }

Closing this issue, since I'm not going to implement it. But a PR is welcome.