Support custom media type

[Kiryl Bubovich]

Hi! I have the following code

@GET
@Operation(
        ...
        responses = {
                @ApiResponse(
                        responseCode = "200",
                        content = @Content(
                                examples = {
                                        @ExampleObject(
                                                name = "Some name",
                                                value = "Some Value"
                                        )
                                }
                        ))
        })
@Produces("customMediaType")
public A fetchFont() {
    ... 
}

with this code the following piece of documentation will appear in swagger.json

"200" : {
    "content" : {
        "customMediaType" : {
            "examples" : {
                "Some name" : {
                    "value" :  "Some value"
                }
            }
        }
    }
}

However, when converting json to md using widdershins, this section is not displayed. This is due to the custom media type.
Thanks in advance for any effort on this issue!

[Mike Ralphson]

Is customMediaType a placeholder or the actual value you are using? According to the spec, the keys within a content object should be "a media type or media type range". To be a valid media type the key would need to have a type then a / then a subtype.

In any case, Widdershins only knows how to represent schemas and examples if they are JSON, YAML, XML or text based. Other types such as image/* or application/pdf are not supported for the display of schemas or examples.

[KiperUladzislau]

@MikeRalphson Thanks for quick reply, by the way, do you plan to support other types such as application/* ?

[Mike Ralphson]

Unfortunately application/* covers such a wide range of media-types (e.g. application/octet-stream, application/pdf, application/zip, application/msword etc) that I don't immediately see a reasonable way to provide rendering for them. Open to suggestions though!

If your custom media-type value is based on JSON (which it might be, given your examples value) if you use application/whatever+json it should work as-is.

[Kiryl Bubovich]

The custom MediaType is a placeholder.
For now when we have a custom media type, it appears in the resulting md file as
Accept: customMediaType
but response examples are not displayed. It seems that not showing examples of responses in the case of an unknown media type is a pretty tough 😃. How about representing examples with unknown media type as text/plain?

[Mike Ralphson]

@KirylBubovich would certainly look at an option to support this. Do you have any time to work up a PR?

[Yuliya Ivaniukovich]

Hi @MikeRalphson, just created #462 with potential solution