我这么玩Web Api(一)
帮助页面或用户手册(Microsoft and Swashbuckle Help Page)
前言
你需要为客户编写Api调用手册?你需要测试你的Api接口?你需要和前端进行接口对接?那么这篇文章应该可以帮到你。本文将介绍创建Web Api 帮助文档页面的两种方式,Microsoft Help Page和Swashbuckle Help Page。
编写RESTful的Web Api
/// <summary>
/// 股票数据接口 /// </summary>
[RoutePrefix("api/stocks")] public class StocksController : ApiController
{ private readonly List<Stock> _stocks; /// <summary>
/// 构造函数 /// </summary>
public StocksController()
{
_stocks = new List<Stock>
{ new Stock{Symbol = "000001", Name = "平安银行", Exchange = "深证交易所"}, new Stock{Symbol = "000002", Name = "万科A", Exchange = "深证交易所"}, new Stock{Symbol = "000003", Name = "PT金田A", Exchange = "深证交易所"}, new Stock{Symbol = "000004", Name = "国农科技", Exchange = "深证交易所"}, new Stock{Symbol = "000005", Name = "世纪星源", Exchange = "深证交易所"}
};
} /// <summary>
/// 获取股票列表 /// </summary>
/// <returns>股票列表</returns> [HttpGet] public IEnumerable<Stock> List()
{ return _stocks;
} /// <summary>
/// 获取指定股票 /// </summary>
/// <param name="symbol">股票代码</param>
/// <returns>指定股票</returns>
[HttpGet(), Route("{symbol}", Name = "Get")] public IHttpActionResult Get(string symbol)
{ var stock = _stocks.SingleOrDefault(n => n.Symbol == symbol); if (stock == null)
{ return NotFound();
} return Ok(stock);
} /// <summary>
/// 添加一支股票 /// </summary>
/// <param name="stock">股票信息</param> [HttpPost] public IHttpActionResult Create(Stock stock)
{ return CreatedAtRoute("Get", new { symbol = stock.Symbol }, stock);
} /// <summary>
/// 更新一支股票 /// </summary>
/// <param name="stock">股票信息</param> [HttpPut] public IHttpActionResult Update(Stock stock)
{ if (_stocks.All(n => n.Symbol != stock.Symbol))
{ return NotFound();
} return StatusCode(HttpStatusCode.NoContent);
} /// <summary>
/// 部分更新一支股票 /// </summary>
/// <param name="symbol">股票代码</param>
/// <param name="form">需要更新的股票信息</param>
[HttpPatch, Route("{symbol}")] public IHttpActionResult PartialUpdate(string symbol, PartialForm form)
{ if (_stocks.All(n => n.Symbol != symbol))
{ return NotFound();
} return StatusCode(HttpStatusCode.NoContent);
} /// <summary>
/// 删除一支股票 /// </summary>
/// <param name="symbol">股票代码</param>
/// <returns>是否删除成功</returns>
[HttpDelete, Route("{symbol}")] public IHttpActionResult Delete(string symbol)
{ if (_stocks.All(n => n.Symbol != symbol))
{ return NotFound();
} return Ok(true);
} /// <summary>
/// 这个方法不会显示到帮助页面 /// </summary>
[HttpGet, Route("hide")]
[ApiExplorerSettings(IgnoreApi = true)] public void NotShow()
{
}
}
Microsoft Help Page
1.在Nuget添加Help Page组件。
组件添加完后,会自动生成帮助页面,文件存在区域(Areas)中
2.注册区域(Areas)
在Global.asax文件中的Application_Start()方法添加以下代码:
AreaRegistration.RegisterAllAreas();
浏览生成的帮助页面:http://localhost:xxxx/help
Web API的方法列表已经显示出来了,但是方法的描述还是默认的描述。
3. 修改配置文件生成位置 右键项目属性,指定输出xml。
修改AreasHelpPageApp_StartHelpPageConfig.cs中register方法里指定的xml路径为上述指定输出的路径。
再查看帮助页面,方法描述已经和代码注释一致。
注:这里可根据需要把Area中对应页面的英文词条更新成中文,当然样式也可以调整。
4.添加测试工具
在Nuget添加Test Client组件。
在AreasHelpPageViewsHelpApi.cshtml添加以下代码:
@Html.DisplayForModel("TestClientDialogs")
@section Scripts {
<link type="text/css" href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" />
@Html.DisplayForModel("TestClientReferences")
}
再次运行Help Page,每个API说明页面的右下角会多一个测试的按钮。
4.参考
http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages
Swashbuckle Help Page
1.在Nuget添加Swashbuckle组件。
然后就可以浏览生成的帮助页面:http://localhost:xxxx/swagger
Web API的方法列表已经显示出来了,但是方法的描述还没有显示出来。
2. 修改配置文件生成位置 右键项目属性,指定输出xml。
找到SwaggerConfig.cs
把 c.IncludeXmlComments(GetXmlCommentsPath())的注释去掉
实现GetXmlCommentsPath()方法,指定xml路径为上述指定输出的路径。
再查看帮助页面,方法描述已经和代码注释一致。
2. 常见异常
用Nuget引用dll的时候,它会在config中添加依赖项信息,但偶尔会没添加,这时会出现Could not load file or assembly 'XXX' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)异常。
此时只要在config中添加对应的依赖项就好
4.帮助页面词条及样式调整
如果要修改或编辑Swashbuckle Help Page的样式或词条,需要编辑SwaggerConfig.cs,相对Microsoft Help Page可能要复杂一点(我只改过Microsoft的,没改过Swashbuckle的)。具体如何修改可参考:https://github.com/domaindrivendev/Swashbuckle
简单总结
Swashbuckle Help Page搭建起来相对会比较简单,但是样式(自带swagger logo)和词条修改会较麻烦一点,因此,比较适合作为内部接口说明几接口调用测试。
Microsoft Help Page搭建起来相对要麻烦一点点,但是样式和词条修改会方便一点,因此,比较适合作为外部接口调用使用文档。
源码下载
https://github.com/ErikXu/WebApi.HelpPage
- Python接口自动化-7-unittest
- cobbler自动安装系统(Centos7.X)
- Linux NTP时间服务器
- 子查询的另一种方式——映射
- LNMP架构之搭建wordpress博客网站
- Nginx的各种报错总结
- 谷歌TensorFlowLite正式发布,机器学习框架向移动端大步挺进!
- ABP+AdminLTE+Bootstrap Table权限管理系统一期
- 18888元秒下的域名sdhlx.com已建站
- 锂离子电池发明人:自动驾驶汽车电池需要更加耐用
- Linux中MySQL5.6编译安装与MySQL5.7二进制安装步骤
- Nginx服务编译安装、日志功能、状态模块及访问认证模式实操
- 快速入门系列--WebAPI--03框架你值得拥有
- 快速入门系列--MVC--06视图
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- 在页面部分没有发现字符集声明,请增加该声明
- Linux使用Sudo委派权限
- linux实现定时备份mysql数据库的简单方法
- linux确认已经卸载数据盘并可以新建自定义镜像
- 在Linux中查看进程占用的端口号
- Linux里Makefile是什么?它是如何工作的?
- 详解Linux文件系统:ext4及更高版本
- Linux设置虚拟内存的教学与实战教程
- 详解Linux服务器状态、性能相关命令
- 【s3cmd】给s3cmd加点debug日志再编一个
- Linux获取当前脚本真实路径的方法
- 短视频商城源码,商城左侧菜单栏网页模板
- 谈一谈Linux系统重要的子目录问题
- Tensorflow 2.x Java api的maven包怎么找
- Linux上也有10个流行的Windows应用程序