返回类型为HttpResponseMessage的自动生成帮助页

Question

我希望对web api自动生成的帮助页面进行一些澄清。

据我所知，如果我返回一个Type，它将自动生成带有示例的该操作的帮助页面。但是如果我使用Http响应消息，那么它无法猜测响应将是什么并且只能对请求参数进行假设是可以理解的。

我使用 HttpResponse 消息的原因是，当状态代码可能与 200 不同时，建议指示您希望返回的状态代码。

那么，什么是能够返回您想要的状态代码的最佳实践方法，但仍然有帮助页面计算出您要返回的类型？

Answer 1

MVC 5有一个内置属性来设置响应类型。

更多信息请点击这里：http://thesoftwaredudeblog.wordpress.com/2014/01/05/webapi-2-helppage-using-responsetype-attribute-instead-of-setactualresponsetype/

只需使用：

    ResponseType(typeof([Your_Class]))]

Answer 2

我认为这个属性是一个很棒的想法，所以我实现了一个属性，它可能会帮助其他人，直到你们发布它。

用属性修饰您的操作:

public class FooController : ApiController
{
    [ResponseType(typeof(Bar))]
    public HttpResponseMessage Get(string id)
    {
        // ...
    }
}

定义属性:

[AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
public class ResponseTypeAttribute : Attribute
{
   public ResponseTypeAttribute(Type type)
   {
       if (type == null)
       {
           throw new ArgumentNullException("type");
       }

       Type = type;
   }

   public Type Type { get; private set; }
}

定义注册响应类型的方法：

/// <summary>
///     Registers api controller actions which return HttpResponseMessage
///     and include the ResponseType attribute to be populated with web api
///     auto generated help.
/// </summary>
/// <param name="assembly">The assembly to search for</param>
public static void RegisterHelpResponseTypes(Assembly assembly)
{
    var apiControllerTypes = assembly
        .GetTypes().Where(typeof(ApiController).IsAssignableFrom);

    foreach (var apiControllerType in apiControllerTypes)
    {
        var validActions = apiControllerType.GetMethods()
            .Where(method =>
                Attribute.IsDefined(method, typeof(ResponseTypeAttribute))
                &&
                (method.ReturnType == typeof(HttpResponseMessage)));

        foreach (var action in validActions)
        {
            var responseType = (ResponseTypeAttribute)Attribute
                                    .GetCustomAttributes(action)
                                    .Single(x => x is ResponseTypeAttribute);

            var controllerName = apiControllerType.Name.Substring(0, 
                    apiControllerType.Name.LastIndexOf("Controller", 
                                        StringComparison.OrdinalIgnoreCase));
            var actionName = action.Name;

            GlobalConfiguration
                .Configuration
                .SetActualResponseType(responseType.Type, 
                                       controllerName, 
                                       actionName);
        }
    }
}

在应用程序启动时包括它:

RegisterHelpResponseTypes(typeof(FooController).Assembly);

如果您发现任何问题，请告诉我。

Answer 3

对于需要返回 HttpResponse 消息的这些方案，解决方法是使用帮助页提供的一些帮助程序来指示该特定操作的实际返回类型。您可以在路径“区域”\“帮助页”\App_Start\“帮助页配置”中找到以下代码.cs

//// Uncomment the following to correct the sample response when the action returns an HttpResponseMessage with ObjectContent<string>.
//// The sample will be generated as if the controller named "Values" and action named "Post" were returning a string.
//config.SetActualResponseType(typeof(string), "Values", "Post");

注意：
在即将发布的版本中，我们将引入一个名为“系统.Web.描述.响应类型属性”的新属性，您可以向该属性提供指示响应实际类型的系统类型。通过这种方式，您可以从您的操作中返回HttpResponseMessage或IHttpActionResult，并且仍然期望HelpPage工作。