ASP.NET WebApi Document Helper

本项目实现了ASP.NET WebApi 接口文档的自动生成功能。

微软出的ASP.NET WebApi Help Page固然好用，但是我们项目基于Owin 平台的纯WebApi 项目，不想引入MVC 的依赖，因此我们需要定制下ASP.NET WebApi Help Page。

首先来个学生习作版本：

var info = typeof(AccountController);
var sb = new StringBuilder();
var methods = info.GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly);
foreach (var m in methods)
{
    sb.AppendLine(m.Name);
    var pi = m.GetParameters();
    //Get Http Method
    var postAtts = m.GetCustomAttributes(typeof(HttpPostAttribute), false);
    if (postAtts.Count() != 0)
    {
        sb.AppendLine("POST");
    }
    else
    {
        sb.AppendLine("GET");
    }
    //Get Route
    var routeAtts = m.GetCustomAttributes(typeof(RouteAttribute), false);
    if (postAtts.Count() != 0)
    {
        var routeTemp = (RouteAttribute)routeAtts[0];
        sb.AppendLine(routeTemp.Template);
    }

    //Get parameter
    foreach (ParameterInfo t in pi)
    {
        var tt = t.ParameterType;

        if (tt == typeof(string))
        {
            sb.AppendLine("Query String : " + t.Name + "={string}");
        }
        else if (tt == typeof(Guid))
        {
            sb.AppendLine("Query String Or URL : " + t.Name + "={guid}");
        }
        else if (tt.BaseType == typeof(Enum))
        {
            sb.AppendLine("Query String : " + t.Name + "={Enum}");
        }
        else if (tt.BaseType == typeof(object))
        {
            var paramter = Activator.CreateInstance(tt);
            var json = JsonHelper.ToJsonString(paramter);
            json = json.Replace("null", "\"string\"");
            sb.AppendLine(json);
        }
    }
    sb.AppendLine();
}

var result = sb.ToString();

这种东西只能写作业的时候随便写写，用到项目中还是差点火候的。我们接下去进入正题。帮助页面必然分为一个Index, 一个Detail。Index 页面需要获取所有的Controller 以及下面的Action。研究了下代码，发现系统以及给我们封装好了对应的方法，直接调用即可。

 [HttpGet]
    [Route("api/Helps")]
    public HttpResponseMessage Index()
    {
        var descriptions = Configuration.Services.GetApiExplorer().ApiDescriptions;
        var groups = descriptions.ToLookup(api => api.ActionDescriptor.ControllerDescriptor);

        StringBuilder html = GetHtmlFromDescriptionGroup(groups);
        var response = this.Request.CreateResponse();
        response.Content = new StringContent(html.ToString(), Encoding.UTF8, "text/HTML");

        return response;
    }

由于是纯API的，返回的HTML就不用什么模板了，直接拼接字符串搞定。

Index 向Detail 跳转，这里有一个有意思的方法：

 public static string GetFriendlyId(this ApiDescription description)
    {
        string path = description.RelativePath;
        string[] urlParts = path.Split('?');
        string localPath = urlParts[0];
        string queryKeyString = null;
        if (urlParts.Length > 1)
        {
            string query = urlParts[1];
            string[] queryKeys = HttpUtility.ParseQueryString(query).AllKeys;
            queryKeyString = String.Join("_", queryKeys);
        }

        StringBuilder friendlyPath = new StringBuilder();
        friendlyPath.AppendFormat("{0}-{1}",
            description.HttpMethod.Method,
            localPath.Replace("/", "-").Replace("{", String.Empty).Replace("}", String.Empty));
        if (queryKeyString != null)
        {
            friendlyPath.AppendFormat("_{0}", queryKeyString.Replace('.', '-'));
        }
        return friendlyPath.ToString();
    }

然后在详情界面里解析出我们需要的参数，以及自动生成sample

      [HttpGet]
    [Route("api/Helps/Detail")]
    public HttpResponseMessage Detail(string apiId)
    {
        var apiModel = Configuration.GetHelpPageApiModel(apiId);
        var html = GetHtmlFromApiModel(apiModel);

        var response = this.Request.CreateResponse();
        response.Content = new StringContent(html.ToString(), Encoding.UTF8, "text/HTML");

        return response;
    }

大概耗时3个hour,最后发现基本上是直接搬运了代码，用StringBuilder 代替了view 部分就完成了我们想要的功能，一种搬砖的感觉油然而生，这样的感觉不好。