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帮助文档的更多相关文章
- 从多个XML文档中读取数据用于显示webapi帮助文档
前言: 你先得知道HelpPageConfig文件,不知道说明你现在不需要这个,所以下文就不用看了,等知道了再看也不急.当然如果你很知道这个,下文也不用看了,因为你会了. 方法一: new XmlDo ...
- 生成自己的Webapi帮助文档(一)
最近Webapi接口的开发刚刚进入尾声,随之而来的是让用户知道接口的详细参数信息,看过淘宝的接口文档,但网上没找到他的实现方式 虽然新建Webapi时C#也会给你一个帮助文档的Area,但是总觉得有些 ...
- netcore webapi帮助文档设置
如何建 .netcore webapi 项目这个就不说了,这个都没有没必要看下去. 我这里是.netcore 2.0,虽然没测过1.0的,但想来差不多. 1.Nuget Packages安装,使用程序 ...
- ASP.NET WebAPI 测试文档 (Swagger)
ASP.NET WebAPI使用Swagger生成测试文档 SwaggerUI是一个简单的Restful API测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON配置显示API .项目 ...
- webapi help文档 添加测试功能
在做webapi项目的时候 webapi为我们提供了help文档,开发者可以参考这个文档,但是这个文档缺少测试功能,如果加上一个测试的功能就更加方便了 于是就研究了下写了一段代码,代码比较简单,只要将 ...
- .NET Core WebApi帮助文档使用Swagger生成Api说明文档
Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为什么选择 ...
- 离线安装swashbuckle(webapi自动文档及测试工具)
1.找到已经成功安装过的项目根目录的packages文件夹拷贝到新的项目的根目录 2.vs设置nuget程序包源 将源:地址改为新项目的packages文件夹 3.重新编译并修改代码 右键项目-> ...
- 生成自己的Webapi帮助文档(二)
经过今天一上午的修改,已经有个基础的框架了,其它功能只能是在实际使用中发现一个修改一个了. 以下是生成的结果示例: 相比昨天,几个Model都有修改,这里就不一一贴代码了,放个代码包上来,有需要的自己 ...
- webapi帮助文档swagger
nuget安装Swashbuckle包 修改SwaggerConfig文件 //c.IncludeXmlComments(GetXmlCommentsPath()); //设置接口描述xml路径地址 ...
随机推荐
- "CoolReaper" --酷派手机后门
文章转自:http://drops.wooyun.org/tips/4342 注:译文未获得平底锅授权,纯属学习性质翻译 原文:https://www.paloaltonetworks.com/con ...
- 使用PHP顶替JS有趣DOM
較简单,我须要把一个导航页的数据整理好写入数据库.一个比較直观的方法是对html文件进行分析.通用的方法是用php的正則表達式来匹配.可是这样做开发和维护都非常困难,代码可读性非常差. 导航页的数据都 ...
- JAVA8,SPRING,ANGULARJS对项目
java8+spring+angularjs 项目应用 最近有写一个电子订单商务网站,使用JAVA8,SPRING,ANGULARJS对项目使用的技术和大家分享. 第一次写博客,哪有不对需要改正的请联 ...
- bash shell:重定向标准错误输出
如何重定向标准错误输出到标准输出?如何把标准错误输出输出到一个文件? Bash提供了I/O重定向工具,有3个缺省的文件(标准输出流): stdin - 用来获取输入,比如键盘.文件重定向 stdout ...
- XEvent – SQL Server Log文件对磁盘的写操作大小是多少
原文:XEvent – SQL Server Log文件对磁盘的写操作大小是多少 本篇是上一篇SQL Server Log文件对磁盘的写操作大小是多少的续,使用XEvent收集SQL Server D ...
- ProgressDialog(四)——更改系统自带ProgressDialog文字大小
MainActivity如下面: package com.example.ttt; import android.app.Activity; import android.app.ProgressDi ...
- Matlab学习第二天 利用插值
插入值一切手段: watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvdTAxNDQ5MjI1Nw==/font/5a6L5L2T/fontsize/400/fi ...
- 安裝 Rails 開發環境
安裝 Rails 開發環境 Give someone a program, you frustrate them for a day; teach them how to program, you f ...
- 苹果新的编程语言 Swift 语言进阶(十二)--选项链
选项链是使用选项来查询和调用其属性.方法或下标的一个过程,假设选项包括一个值,则属性.方法.下标的查询和调用成功,否则,调用返回nil. 选项链能用在不论什么类型的选项来检查对其一个属性.方法.下标的 ...
- 当有多于64合乎逻辑的cpu时刻,Windows 下一个Oracle db 实例启动(startup)什么时候会hang(待定)
Bug 9772171 - Database startup hangs on Windows when machine has more than 64 cores [ID 9772171.8] 该 ...