Question

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

据我所知，如果我返回一个Type，它将自动生成该操作的帮助页面并附带一个示例。但是，如果我使用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]))]

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

3 个答案: