生成自己的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; }
    }