Swashbuckle integration not populating "produces" field in the swagger.json with version media type parameter

[douggish]

I'm trying the "SwaggerSample" from the repository from the tagged 3.1.0 release, except I changed it to use media type versioning by specifying the MediaTypeVersionReader as shown here:

services.AddApiVersioning(
    options =>
    {
        // reporting api versions will return the headers "api-supported-versions" and "api-deprecated-versions"
        options.ReportApiVersions = true;
        options.ApiVersionReader = new MediaTypeApiVersionReader();
    } );

I started up the service and went to the Swagger UI, selected the V2 spec and tried to do a GET on /api/Orders through the Swagger UI. This failed with a 400 and a response body of:

{
  "error": {
    "code": "ApiVersionUnspecified",
    "message": "An API version is required, but was not specified.",
    "innerError": null
  }
}

The accept header is set to "application/json" (instead of "application/json; v=2.0") in the request: curl -X GET "http://localhost:5000/api/Orders" -H "accept: application/json", and I can see no way of changing that through the Swagger UI since "application/json" is the only option in the "Response content type" drop down.

I think the options in the "Response context type" are driven by the "produces" field in the swagger.json. See the swagger.json below:

{"swagger":"2.0","info":{"version":"2.0","title":"Sample API","description":"A sample application with Swagger, Swashbuckle, and API versioning.","termsOfService":"Shareware","contact":{"name":"Bill Mei","email":"bill.mei@somewhere.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"paths":{"/api/Orders":{"get":{"tags":["Orders"],"summary":"Retrieves all orders.","operationId":"Get","consumes":[],"produces":["application/json"],"parameters":[],"responses":{"200":{"description":"The successfully retrieved orders.","schema":{"uniqueItems":false,"type":"array","items":{"$ref":"#/definitions/Order"}}}}},"post":{"tags":["Orders"],"summary":"Places a new order.","operationId":"Post","consumes":["application/json-patch+json; v=2.0","application/json; v=2.0","text/json; v=2.0","application/*+json; v=2.0"],"produces":["application/json"],"parameters":[{"name":"order","in":"body","description":"The order to place.","required":false,"schema":{"$ref":"#/definitions/Order"}}],"responses":{"201":{"description":"The order was successfully placed.","schema":{"$ref":"#/definitions/Order"}},"400":{"description":"The order is invalid.","schema":{"$ref":"#/definitions/ProblemDetails"}}}}},"/api/Orders/{id}":{"get":{"tags":["Orders"],"summary":"Gets a single order.","operationId":"GetOrderById-V2","consumes":[],"produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"The requested order identifier.","required":true,"type":"integer","format":"int32"}],"responses":{"200":{"description":"The order was successfully retrieved.","schema":{"$ref":"#/definitions/Order"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ProblemDetails"}},"404":{"description":"The order does not exist.","schema":{"$ref":"#/definitions/ProblemDetails"}}}}},"/api/v{api-version}/People":{"get":{"tags":["People"],"summary":"Gets all people.","operationId":"Get","consumes":[],"produces":["application/json"],"parameters":[{"name":"api-version","in":"path","required":true,"type":"string"}],"responses":{"200":{"description":"The successfully retrieved people.","schema":{"uniqueItems":false,"type":"array","items":{"$ref":"#/definitions/Person"}}}}}},"/api/v{api-version}/People/{id}":{"get":{"tags":["People"],"summary":"Gets a single person.","operationId":"GetPersonByIdV2","consumes":[],"produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"The requested person identifier.","required":true,"type":"integer","format":"int32"},{"name":"api-version","in":"path","required":true,"type":"string"}],"responses":{"200":{"description":"The person was successfully retrieved.","schema":{"$ref":"#/definitions/Person"}},"404":{"description":"The person does not exist.","schema":{"$ref":"#/definitions/ProblemDetails"}}}}}},"definitions":{"Order":{"description":"Represents an order.","required":["customer"],"type":"object","properties":{"id":{"format":"int32","description":"Gets or sets the unique identifier for the order.","type":"integer"},"createdDate":{"format":"date-time","description":"Gets or sets the date and time when the order was created.","type":"string"},"effectiveDate":{"format":"date-time","description":"Gets or sets the date and time when the order becomes effective.","type":"string"},"customer":{"description":"Gets or sets the name of the ordering customer.","type":"string"}}},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{"type":"object"}},"Person":{"description":"Represents a person.","required":["firstName","lastName"],"type":"object","properties":{"id":{"format":"int32","description":"Gets or sets the unique identifier for a person.","type":"integer"},"firstName":{"description":"Gets or sets the first name of a person.","maxLength":25,"minLength":0,"type":"string"},"lastName":{"description":"Gets or sets the last name of a person.","maxLength":25,"minLength":0,"type":"string"},"email":{"description":"Gets or sets the email address for a person.","type":"string"}}}}}

The "consumes" fields seem to have the v=2.0 media type parameter, but not the "produces" fields.

[commonsensesoftware]

It took me a while to figure this out myself. At least in Swashbuckle, its considering the ProducesAttribute before the API Explorer, which feels wrong to me. The API Versioning API Explorer is definitely producing the correct values. You can see it here. I suspect this behavior is because if you get an API description, it will definitely have some response type and this attribute is being used as an override; however, my understanding is the API Explorer would already do this so it shouldn't be necessary and causes an issue in this particular case.

The solution is to simply remove the [Produces("application/json")] decorations from your actions and you should be back in business.

I'll consider whether to also remove it from the samples. This issue appears to be specific to Swashbuckle and versioning by media type. The API Explorer definitely reported the correct request and response formats that get mapped to consumes and produces in the Swagger document. You don't see the produces because the Swashbuckle Swagger generator choose the attribute values over the API explorer.

If you feel like posting an issue on the Swashbuckle, I'm happy to participate if you tag me. I hope that helps.

[douggish]

Removing the [Produces("application/json")] attributes seems somewhat undesirable since the generated swagger.json includes additional media types in the produces field:
produces":["text/plain; v=2.0","application/json; v=2.0","text/json; v=2.0"]

Also we would like to use a custom media type: [Produces("vnd.my.company+json")] but use the api-versioning library to add on the version media type parameter (e.g. "vnd.my.company+json; v=2.0").

I did find that if I modified the sample to use Swashbuckle.AspNetCore version 3.0.0, the version parameter showed up in the produces field in the swagger.json, so that seems like an alternative solution for now. I wouldn't want to be stuck on an old release of Swashbuckle.AspNetCore though.

If I post an issue on the Swashbuckle repo, what should I say the exact problem is? That the Produces attribute is overriding the value for produces returned by the API Explorer? Sorry, I'm not super familiar with the API Explorer.

[commonsensesoftware]

You can use a custom media type if you like, you'll just need a custom IApiVersionReader as well. There is no standard of format or convention to consistently extract an API version from a custom media type. The necessary extensibility points are in place, but only you know how to parse of the raw value from the media type.

From what I could tell, there should be no reason for Swashbuckle to override what the API Explorer provides. The API Explorer will provide default media types that can be overridden with the [Consumes] and [Produces] attributes. There's probably a reason why it does that, but it escapes me.

The API Explorer is the thing that actually provides all the API description information. Swagger generators like Swashbuckle use this information to build JSON document. For example, if you leave [Produces("application/json")] on your action and inspect the ApiDescription returned by the API Explorer, you'll see there is only one ApiResponseFormat which has the media type application/json; v=1.0. Since Swashbuckle explicitly checks for and short-circuits if the one of these attributes is present, you don't get the API Explorer behavior. IMO, it's not necessary, but at a minimum, there should be an option to bypass or disable the behavior in Swashbuckle so you don't have to use bizarre tricks to get the result you want.

To get the final result as is, you'll need to do one of the following:

• Enumerate everything returned by the API Explorer and trim down the media types
• Alternately you can create a custom IApiDescriptionProvider, register it with ASP.NET to run after the API versioning API Explorer extensions, and trim down the media types
• Use a Swashbuckle extension (IOperationFilter or something) to trim down media types before they are generated in the Swagger document

[commonsensesoftware]

There were several solution here. Did any of them ultimately work for you? Is there anything else to be resolved on this issue? Thanks.

[douggish]

We ended up using a Swashbuckle Operation Filter to customize the produces array so that it includes the version media type parameter. Thanks for the help.

[commonsensesoftware]

Great! Thanks for confirming.