Webapi帮助文档

生成自己的Webapi帮助文档（一）

最近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; }
    }

 

 

分类: WebApi