22

如何注释我的 ASP.NET WebAPI 操作,以便 swagger 元数据包含我的资源支持的内容类型?

具体来说,我希望文档显示我的一个资源可以返回“原始” application/jsonapplication/xml但现在也可以返回新格式,application/vnd.blah+json或者+xml.

4

4 回答 4

49

扩展@VisualBean 的答案

在控制器的 API 方法中,您可以使用下面的代码来设置属性,例如:

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

注意:“Exclusive=true”将删除所有其他内容类型,否则使用新属性将在 Swagger UI 下拉列表中添加新的响应内容类型。它不会修改您的控制器或 API,只会修改文档。

SwaggerConfig.cs

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

SwaggerResponseContentTypeAttribute.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);
        }
    }
}
于 2016-04-01T05:42:11.350 回答
10

你需要做的是这个; Swagger 规范: 您需要将您的响应类型添加到该操作的响应类型列表中:

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

这可以通过 OperationFilter 来完成。

伪代码传入!!!

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 可以通过[SwaggerOperation("myCustomName")]注解设置。

然后在 swaggerConfig.cs 中应用 operationsFilter:

c.OperationFilter<CustomResponseType>();

注意:operation.operationId == "myCustomName" 您基本上可以为特定路线或其他任何事情做而不是这样做。ApiDescription 提供了很多关于上下文的信息。

于 2016-02-01T11:32:51.047 回答
7

@OzBob 的回答假设您只想向方法添加单个属性。如果要为同一方法添加和记录多个内容类型,可以使用以下内容:

SwaggerResponseContentTypeAttribute.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);
        }
    }
}

请注意,当您在同一方法上有多个属性并且想要替换现有内容类型时,您应该Exclusive = true只设置第一个属性。否则,您不会将所有属性都放入文档中。

于 2017-03-01T10:12:55.433 回答
4

跟随OzBob 的回答。从 Swashbuckle 4.0.x 开始,您可能需要稍微更新操作过滤器代码:

ResponseContentTypeOperationFilter.cs

using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Linq;

public class ResponseContentTypeOperationFilter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        if (!context.ApiDescription.TryGetMethodInfo(out var methodInfo))
        {
            return;
        }
        var requestAttributes = methodInfo.GetCustomAttributes(true).OfType<SwaggerResponseContentTypeAttribute>().FirstOrDefault();

        if (requestAttributes != null)
        {
            if (requestAttributes.Exclusive)
                operation.Produces.Clear();

            operation.Produces.Add(requestAttributes.ResponseType);
        }
    }
}
于 2018-11-15T09:26:50.817 回答