zoukankan      html  css  js  c++  java
  • 生成自己的Webapi帮助文档(一)

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

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

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

    总体思路如下:

    _thumb

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


    
    
    
    
  • 相关阅读:
    android 中文 api (43) —— Chronometer
    SVN客户端清除密码
    Android 中文 API (35) —— ImageSwitcher
    Android 中文API (46) —— SimpleAdapter
    Android 中文 API (28) —— CheckedTextView
    Android 中文 API (36) —— Toast
    Android 中文 API (29) —— CompoundButton
    android 中文 API (41) —— RatingBar.OnRatingBarChangeListener
    Android 中文 API (30) —— CompoundButton.OnCheckedChangeListener
    Android 中文 API (24) —— MultiAutoCompleteTextView.CommaTokenizer
  • 原文地址:https://www.cnblogs.com/smlheart/p/3531552.html
Copyright © 2011-2022 走看看