Swashbuckle Swagger - How to comment on content types?

Question

How can I annotate my ASPAP WebAPI actions so that swagger metadata includes content types that support my resources?

In particular, I want the documentation to show that one of my resources can return the “original” application/json and application/xml , and also now returns the new format application/vnd.blah+json or +xml .

Answer 1

What you need to do is; Swagger specification: you need to add your response type to the response type list for this operation.

 "produces": [ "application/json", "text/json" ], 

This can be done using OperationFilter.

Pseudo-code is incoming !!!

 public class CustomResponseType : IOperationFilter { public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) { if (operation.operationId == "myCustomName") { operation.produces.Add("application/vnd.blah+json"); } } } 

OperationId can be set using the [SwaggerOperation("myCustomName")] annotation.

Then apply the Filter action to swaggerConfig.cs

 c.OperationFilter<CustomResponseType>(); 

Note: instead of operation.operationId == "myCustomName" you could do this for a specific route or something else in principle. ApiDescription provides context information.

Answer 2

@VisualBean answer extension

In the Controller API method, you can use the code below to set the type attribute:

 [SwaggerResponseContentType(responseType:"application/pdf", Exclusive=true)] public HttpResponseMessage GetAuthorityForm(string id) { .... 

Note: "Exclusive = true" will delete all other content types, otherwise using the new attribute will add a new response content type in the Swagger user interface. It will not change your controller or API in the documentation only.

Swaggerconfig.cs

  GlobalConfiguration.Configuration .EnableSwagger(c => // Set filter to apply Custom Content Types to operations // c.OperationFilter<ResponseContentTypeOperationFilter>(); 

SwaggerReponseContentTypeAttribute.cs

 /// <summary> /// SwaggerResponseContentTypeAttribute /// </summary> [AttributeUsage(AttributeTargets.Method)] public sealed class SwaggerResponseContentTypeAttribute : Attribute { /// <summary> /// SwaggerResponseContentTypeAttribute /// </summary> /// <param name="responseType"></param> public SwaggerResponseContentTypeAttribute(string responseType) { ResponseType = responseType; } /// <summary> /// Response Content Type /// </summary> public string ResponseType { get; private set; } /// <summary> /// Remove all other Response Content Types /// </summary> public bool Exclusive { get; set; } } 

ResponseContentTypeOperationFilter.cs

 public class ResponseContentTypeOperationFilter : IOperationFilter { public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) { var requestAttributes = apiDescription.GetControllerAndActionAttributes<SwaggerResponseContentTypeAttribute>().FirstOrDefault(); if (requestAttributes != null) { if (requestAttributes.Exclusive) operation.produces.Clear(); operation.produces.Add(requestAttributes.ResponseType); } } } 

Answer 3

The @OzBob answer assumes that you want to add only one method attribute. If you want to add and document several types of content for the same method, you can use the following:

SwaggerReponseContentTypeAttribute.cs

 /// <summary> /// SwaggerResponseContentTypeAttribute /// </summary> [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] public class SwaggerResponseContentTypeAttribute : Attribute { /// <summary> /// SwaggerResponseContentTypeAttribute /// </summary> /// <param name="responseType"></param> public SwaggerResponseContentTypeAttribute(string responseType) { ResponseType = responseType; } /// <summary> /// Response Content Type /// </summary> public string ResponseType { get; private set; } /// <summary> /// Remove all other Response Content Types /// </summary> public bool Exclusive { get; set; } } 

ResponseContentTypeOperationFilter.cs

 public class ResponseContentTypeOperationFilter : IOperationFilter { public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) { var requestAttributes = apiDescription.GetControllerAndActionAttributes<SwaggerResponseContentTypeAttribute>(); foreach (var requestAttribute in requestAttributes) { if (requestAttribute.Exclusive) { operation.produces.Clear(); } operation.produces.Add(requestAttribute.ResponseType); } } } 

Please note: if you have several attributes of the same method and want to replace existing types of content, you should set Exclusive = true only for the first attribute. Otherwise, you will not get all the attributes in the documentation.