最近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帮助文档(一)的更多相关文章

  1. 生成自己的Webapi帮助文档(二)

    经过今天一上午的修改,已经有个基础的框架了,其它功能只能是在实际使用中发现一个修改一个了. 以下是生成的结果示例: 相比昨天,几个Model都有修改,这里就不一一贴代码了,放个代码包上来,有需要的自己 ...

  2. Webapi帮助文档

    生成自己的Webapi帮助文档(一) 最近Webapi接口的开发刚刚进入尾声,随之而来的是让用户知道接口的详细参数信息,看过淘宝的接口文档,但网上没找到他的实现方式 虽然新建Webapi时C#也会给你 ...

  3. .NET Core WebApi帮助文档使用Swagger生成Api说明文档

    Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为什么选择 ...

  4. 离线安装swashbuckle(webapi自动文档及测试工具)

    1.找到已经成功安装过的项目根目录的packages文件夹拷贝到新的项目的根目录 2.vs设置nuget程序包源 将源:地址改为新项目的packages文件夹 3.重新编译并修改代码 右键项目-> ...

  5. .NET项目工程生成一份项目帮助文档chm--Sandcastle工具

    Sandcastle的,由Microsoft创建的,是从创建MSDN风格的文档中使用的工具.NET程序集和关联的XML注释文件.目前的版本是 2010年6月发布.这是命令行并没有GUI前端,项目管理功 ...

  6. 从多个XML文档中读取数据用于显示webapi帮助文档

    前言: 你先得知道HelpPageConfig文件,不知道说明你现在不需要这个,所以下文就不用看了,等知道了再看也不急.当然如果你很知道这个,下文也不用看了,因为你会了. 方法一: new XmlDo ...

  7. 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档

    博客搬到了fresky.github.io - Dawei XU,请各位看官挪步.最新的一篇是:用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档.

  8. 使用Sandcastle工具为.NET项目工程生成一份项目帮助文档chm

    Sandcastle的,由Microsoft创建的,是从创建MSDN风格的文档中使用的工具.NET程序集和关联的XML注释文件.目前的版本是2010年6月发布.这是命令行并没有GUI前端,项目管理功能 ...

  9. 生成基于Maven的项目文档站点

    在Maven中,可以使用“mvn site”,为您的项目信息生成文档站点. mvn site 生成的网站是在项目的“target/site”文件夹中. mvn site 示例 请参见通过“mvn si ...

随机推荐

  1. TableLayout中stretchColumns、shrinkColumns的使用方法

    android:stretchColumns="1" android:shrinkColumns="1"这两个属性是TableLayout所特有的,也是这两个属 ...

  2. hdu Text Reverse

    题目链接:http://acm.hdu.edu.cn/showproblem.php?pid=1062 单词翻转! 代码: #include <stdio.h> #include < ...

  3. e.target 和 e.srcElement 的使用问题

    ie 下的event.srcElement从字面上可以看出来有以下关键字:事件.源(它的意思就是:当前事件的源), 我们可以调用他的各种属性就像:document.getElementById(&qu ...

  4. Before和After用法小结

    Before和After用法小结 定义 :before 选择器在被选元素的内容前面插入内容.:after选择器在被选元素的内容后面插入内容.(注:必须包含content 属性) 一.特性:不能左右:e ...

  5. BZOJ 1025 SCOI2009 游戏 动态规划

    标题效果:特定n.行定义一个替代品1~n这种更换周期发生后,T次要(T>0)返回到原来的顺序 找到行的所有可能的数 循环置换分解成若干个,然后行位移数是这些周期的长度的最小公倍数 因此,对于一些 ...

  6. 采用RedisLive监控Redis服务

    1.基础环境安装https://pypi.python.org/packages/source/b/backports.ssl_match_hostname/backports.ssl_match_h ...

  7. 【SSH三框架】Struts2第一章的基础:第一次写Struts2规划

    今年八月,当已经SSH三架完成学业.然后,他感动Android开展.三个框架已经很长的时间做无用的东西.所以,如果你想花三四天的时间来复习一下,写在博客. 附带SSH整个jar包网盘下载:http:/ ...

  8. 【专访】【Spring常见问题汇总】【05】

    种: 传播行为:传播行为定义了client与彼调用方法之间的事务边界. 隔离级别:隔离级别定义了一个事务可能受其它并发事务影响的程度. 仅仅读:表明事务是否是仅仅读的. 事务超时:指定事务执行的最长时 ...

  9. Asp.Net MVC5入门学习系列②

    原文:Asp.Net MVC5入门学习系列② 添加一个Controller(控制器) 因为我们用的是Asp.Net MVC,MVC最终还是一套框架,所以我们还是需要遵循它才能玩下去,或者说是更好的利用 ...

  10. 对象javascript

    //对象 var lennon=Object(); lennon.name="John"; lennon.year=1940; lennon.living=false; conso ...