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