Media Types

For a given API, request and response contents may be transmitted in different media types - e.g. appliction/json, application/xml etc. OpenAPI 3.0 provides the content field on request body and response descriptions to list supported media types. To learn more about how media types are described by the OpenAPI Specification, checkout out the OpenAPI docs here.

When generating request and response definitions, Swashbuckle will list supported media types according to the input and output formatters configured for your application. For example, if you’re using the SystemTextJsonInputFormatter, then Swashbuckle will include a definition for the following media types on request bodies, because these are the media types explicitly supported by that formatter:

  • application/json
  • text/json
  • application/*+json

It’s worth noting however, that ASP.NET Core does provide the [Consumes] and [Produces] attributes, which can be applied at the action or controller level, to further constrain the media types supported for a given operation or group of operations. In this case, Swashbuckle will honor the behavior and only list the explicitly supported media types.

For example, given the following controller:

Swashbuckle will only generate a single application/json media type for the relevant request body and response definitions:

Note

If you’ve configured your application to support XML media types (as described here), then Swashbuckle will automatically list the additional media type. However, support for honoring XmlSerializer behavior is currently limited and requires some workarounds to generate accurate schema definitions. See XML Media Types for more info.