最近Webapi接口的开发刚刚进入尾声，随之而来的是让用户知道接口的详细参数信息，看过淘宝的接口文档，但网上没找到他的实现方式

虽然新建Webapi时C#也会给你一个帮助文档的Area，但是总觉得有些太复杂了，实用性值得商榷，于是对他做了些阉割，就有了自己的一个版本。

今天只完成了一些基本框架，具体细节有待进一步实现。

总体思路如下：

1：扩展HttpConfiguration的属性来加入自己的帮助文档生成器，

2：在每个Controller中添加该Controller的帮助信息

3：查看HTML时结合ApiDescription信息和2中添加的帮助信息来生成页面

以下为一些代码：

注册自定义帮助解析器：

public static class HelpPageConfigurationExtensions

    {

        /// <summary>

        /// 添加Controller信息到文档生成器中

        /// </summary>

        /// <param name="config">The <see cref="HttpConfiguration"/>.</param>

        /// <param name="sampleObjects">The sample objects.</param>

        public static void SetSampleObjects(this System.Web.Http.HttpConfiguration config, ControllerDocumentModel controller)

        {

            config.GetHelpDocumentGenerator().Controllers.Add(controller);

        }

        /// <summary>

        /// 获取已经注册进来的帮助信息

        /// </summary>

        /// <param name="config"></param>

        /// <returns></returns>

        public static List<ControllerDocumentModel> GetSampleObjects(this System.Web.Http.HttpConfiguration config)

        {

            return config.GetHelpDocumentGenerator().Controllers;

        }

        /// <summary>

        /// 在属性中添加文档生成器

        /// </summary>

        /// <param name="config">The <see cref="HttpConfiguration"/>.</param>

        /// <returns>The help page sample generator.</returns>

        public static ApiHelpDocumentGenerator GetHelpDocumentGenerator(this System.Web.Http.HttpConfiguration config)

        {

            return (ApiHelpDocumentGenerator)config.Properties.GetOrAdd(

                typeof(ApiHelpDocumentGenerator),

                k => new ApiHelpDocumentGenerator());

        }

    }

每个Controller都会实现一个虚方法，所以这里可以反射来统一调用，把每个Controller的帮助信息添加到生成器的列表中。

public class ApiHelpDocumentRegister

    {

        public static void Regist(System.Web.Http.HttpConfiguration config)

        {

            var asm = System.Reflection.Assembly.GetExecutingAssembly();

            var controllerTypeList = asm.GetTypes().Where(x => x.BaseType == typeof(_BaseApiController));

            foreach (var controllerType in controllerTypeList)

            {

                var controller = asm.CreateInstance(controllerType.FullName);

                var method = controllerType.GetMethod("CreateApiHelpDocument",

                    System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);

                try

                {

                    var result = method.Invoke(controller, null);

                    config.SetSampleObjects(result as ControllerDocumentModel);

                }

                catch (NotImplementedException ex)

                {

                    //未实现该方法

                }

                catch (Exception ex)

                {

                    //其它异常

                }

            }

        }

    }

Controller自定义帮助内容

public class ControllerDocumentModel

    {

        public ControllerDocumentModel()

        {

            Actions = new List<ActionDocumentModel>();

        }

        /// <summary>

        /// Controller名称

        /// </summary>

        public string ControllerName { get; set; }

        /// <summary>

        /// Controller说明

        /// </summary>

        public string ControllerSummary { get; set; }

        /// <summary>

        /// Action列表

        /// </summary>

        public List<ActionDocumentModel> Actions { get; set; }

    }

Action自定义帮助内容

public class ActionDocumentModel

    {

        public ActionDocumentModel()

        {

            Params = new List<ParamDocumentModel>();

        }

        /// <summary>

        /// Action名称

        /// </summary>

        public string ActionName { get; set; }

        /// <summary>

        /// Action说明

        /// </summary>

        public string ActionSummary { get; set; }

        /// <summary>

        /// Action参数列表

        /// </summary>

        public List<ParamDocumentModel> Params { get; set; }

        /// <summary>

        /// 返回值类型

        /// </summary>

        public Type ReturnValueType { get; set; }

        /// <summary>

        /// 返回值说明

        /// </summary>

        public string ReturnValueSummary { get; set; }

        /// <summary>

        /// 正常返回值示例

        /// </summary>

        public object ReturnValueSampleObject_Success { get; set; }

        /// <summary>

        /// 发生错误时的返回值示例

        /// </summary>

        public object ReturnValueSampleObject_Failed { get; set; }

    }

参数自定义帮助：

public class ParamDocumentModel

    {

        /// <summary>

        /// 参数名称

        /// </summary>

        public string ParamName { get; set; }

        /// <summary>

        /// 参数来源

        /// </summary>

        public ParameterBindings ParameterBinding { get; set; }

        /// <summary>

        /// 参数说明

        /// </summary>

        public string ParamSummary { get; set; }

        /// <summary>

        /// 参数类型

        /// </summary>

        public Type ParamType { get; set; }

        /// <summary>

        /// 参数示例数据

        /// </summary>

        public object ParamSampleObject { get; set; }

    }