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

Question

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

据我所知，如果我返回一个类型，它将自动生成该操作的帮助页面，并附上一个示例。但是如果我使用 HttpResponseMessage ，那么它无法猜测响应将是什么并且只能对请求参数做出假设是可以理解的。

我使用 HttpResponseMessage 的原因是，当它可能不同于 200 时，建议指明您希望返回的状态码。

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

Answer 1

对于需要返回 HttpResponseMessage 的这些场景，解决方法是使用 HelpPage 提供的一些帮助程序来指示该特定操作的实际返回类型。 可以在Areas\HelpPage\App_Start\HelpPageConfig.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");

注意：
在即将发布的版本中，我们将引入一个名为 System.Web.Http.Description.ResponseTypeAttribute 的新属性，您可以向该属性提供一个 System.Type 指示响应的实际类型。这样，您可以从您的操作中返回 HttpResponseMessage 或 IHttpActionResult，并且仍然希望 HelpPage 能够正常工作。

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

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

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

只需使用：

    ResponseType(typeof([Your_Class]))]