我这么玩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。

  修改Areas\HelpPage\App_Start\HelpPageConfig.cs中register方法里指定的xml路径为上述指定输出的路径。

  再查看帮助页面,方法描述已经和代码注释一致。

  注:这里可根据需要把Area中对应页面的英文词条更新成中文,当然样式也可以调整。

4.添加测试工具

  在Nuget添加Test Client组件。

  在Areas\HelpPage\Views\Help\Api.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

原文发布于微信公众号 - 我为Net狂(dotNetCrazy)

原文发表时间:2016-07-19

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏恰同学骚年

ASP.Net MVC开发基础学习笔记:五、区域、模板页与WebAPI初步

  为了方便大规模网站中的管理大量文件,在ASP.NET MVC 2.0版本中引入了一个新概念—区域(Area)。

1622
来自专栏Java编程技术

Netty学习笔记(一)

Netty是一种可以轻松快速的开发类似协议服务器和客户端网络应用程序的NIO客户端服务器框架,它大大简化了TCP或者UDP服务器的网络编程,但是你仍然可以访问和...

1442
来自专栏GopherCoder

『No19: Gorm 上手指南』

如果你是做后端开发的,日常工作中,除了熟悉编程语言之外,数据库怕是最常用的技术了吧。

5471
来自专栏WindCoder

微信小程序踩坑记-Java基于SSM下的post请求

最近在持续踩微信小程序的坑,canvas和WebSocket的暂时还没找到相关的解决方案,暂时先将post请求无法获取data参数的坑填上。直接附上解决方案,已...

7591
来自专栏JackieZheng

学习Spring——两个你熟悉的不能再熟悉的场景使用

  最近公众号受邀获取了留言和赠送模板的权限,小开心(欢迎去公众号JackieZheng围观)。   我们大致的了解了Spring这个框架对于依赖注入的使用和诠...

2055
来自专栏c#开发者

C#开发终端式短信的原理和方法

简介   没发过短信的年轻人肯定是属于那种受保护的稀有动物,通讯发达的今天短信已经成为人们交流的重要手段,其中也蕴含着巨大的市场和经济利益,掌握短信技术的人才也...

3969
来自专栏coolblog.xyz技术专栏

Spring IOC 容器源码分析系列文章导读

Spring 是一个轻量级的企业级应用开发框架,于 2004 年由 Rod Johnson 发布了 1.0 版本。经过十几年的迭代,现在的 Spring 框架已...

1393
来自专栏智能大石头

线程池ThreadPool及Task调度机制分析

近1年,偶尔发生应用系统启动时某些操作超时的问题,特别在使用4核心Surface以后。笔记本和台式机比较少遇到,服务器则基本上没有遇到过。

1030
来自专栏JavaEdge

Redis实践(八)-Sentinal12 主从复制高可用?3 Redis Sentinel 架构4 安装与配置5 安装与演示6 客户端11 三个定时任务12 主观下线和客观下线13 领导者选举14

由于Redis Sentinel只会对主节点进行故障转移,对从节点采取主观的下线,所以需要自定义一个客户端来监控对应的事件

1731
来自专栏FreeBuf

开源BUG跟踪平台JIRA目录遍历漏洞分析

作者 Taskiller 最近,一则新发布的公告报告了一个影响Jira 5.0.11和6.0.3版本的目录遍历漏洞,该漏洞在去年7月份被验证,并在接下来的几个月...

3756

扫码关注云+社区