使用swagger实现web api在线接口文档(转载)
一、前言
通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址、参数、返回值、备注等等;像我们以前的做法是写在word/excel,通常是按模块划分,例如一个模块包含n个接口,就形成一个文档,然后再用版本控制管理。这样做的缺点是:
1.不够直观,每次打开文档查看接口很麻烦
2.文档的维护难度大
3.调用方和测试人员使用麻烦,需要先去找接口,在用相应的工具测试(例如使用浏览器还可能要安装插件)
我们希望是可以直接在线浏览,然后直接用浏览器测试。而接口的详细描述都在程序里用注释完成。swagger就可以完成这个工作(ps好像很多开发人员都还不知道这个东西。。。)。
二、使用Swagger
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
在web api 使用swagger可以说非常简单,不需要编写任何代码,完全依赖于插件。具体步骤如下:
1.新建一个web api项目
2.使用nuget添加Swashbuckle包
3.完成
没错,就是这么简单!运行项目,转到地址 http://localhost:57700/swagger/ui/index 会看到如下页面,这是默认添加的两个apicontroller:
这个时候接口还没有具体的描述信息等,例如我们给ValuesController.Get添加注释描述,在页面上还是没有显示出来。需要按照如下步骤实现:
1. 在app_start 下 SwaggerConfig 大100行的位置找到 //c.IncludeXmlComments(GetXmlCommentsPath()); 如下注释,改为:c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name)); (注意去掉注释了)
2. 在SwaggerConfig添加一个方法代码:
1
2
3
4
|
protected static string GetXmlCommentsPath( string name) { return string .Format( @"{0}\bin\{1}.XML" , AppDomain.CurrentDomain.BaseDirectory, name); } |
3. 修改项目生成,在bin下对应的xml文件可以看到具体的描述文档,如下:
重新生成项目,就要可以看到完整的接口描述了。例如我们心中一个TestController如下:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
/// <summary> /// 测试控制器 /// </summary> public class TestController : ApiController { /// <summary> /// 测试Get方法 /// </summary> /// <remarks>测试Get方法</remarks> /// <returns></returns> [HttpGet] public string Get() { return "Get" ; } /// <summary> /// 测试Post方法 /// </summary> /// <param name="name">姓名</param> /// <param name="age">年龄</param> /// <remarks>测试Post方法</remarks> /// <returns></returns> [HttpPost] public string Post( string name, int age) { return name + age.ToString(); } } |
生成的页面如下,可以看到接口的描述,点击Try it out 即可调用:
三、非依赖代码
上面的方式依赖于Swashbuckle包,它已经包含了Swagger-UI组件。我们的代码需要引入这个包,实际上也可以不需要在项目中引入,单独部署Swagger,包括Swagger-Ui(api展示) 和 Swagger-Editor(在线编辑器),它需要依赖nodejs环境,所以需要先按照nodejs。部署其实也很简单,例如这是我部署的结果:
swagger-editor:
swagger-ui:
编辑后只需要将文件保存为json文件,然后拷贝到指定的目录即可。这个部署也非常简单,具体可以参照:
2.http://blog.csdn.net/ron03129596/article/details/53559803
四、总结
规范化api的编写和注释,以及标准化文档,对于团队的开发效率有很大的提升,也有利于项目的维护。例如使用在线接口文档后,测试人员测试只需要在页面输入参数,点击调用就可以看到调用结果。
swagger 也有在线版的,不需要要自己部署。实际上非代码依赖的方式反而更麻烦,使用代码依赖的方法可以像平时我们写注释一样就可以,既能在程序里描述,方便开发人员了解接口功能,也可以在在线展示,发布调用方和测试人员调用。
转载地址:https://www.cnblogs.com/4littleProgrammer/p/6713627.html
使用swagger实现web api在线接口文档(转载)的更多相关文章
- 使用swagger实现web api在线接口文档
一.前言 通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址.参数.返回值.备注等等:像我们以前的做法是写在word/excel,通常是按模块划分,例如一个 ...
- .NET Core WEB API使用Swagger生成在线接口文档
1项目引用Swashbuckle.AspNetCore程序集和Microsoft.Extensions.PlatformAbstractions程序集 右击项目打开"管理NuGet程序包.. ...
- SpringBoot 使用Swagger2打造在线接口文档(附汉化教程)
原文地址: https://www.jianshu.com/p/7e543f0f0bd8 SpringBoot + Swagger2 UI界面-汉化教程 1.默认的英文界面UI 想必很多小伙伴都曾经使 ...
- 第05章—Swagger2打造在线接口文档
spring boot 系列学习记录:http://www.cnblogs.com/jinxiaohang/p/8111057.html 码云源码地址:https://gitee.com/jinxia ...
- 【开源】.Net Api开放接口文档网站
开源地址:http://git.oschina.net/chejiangyi/ApiView 开源QQ群: .net 开源基础服务 238543768 ApiView .net api的接口文档查看 ...
- Java | Spring Boot Swagger2 集成REST ful API 生成接口文档
Spring Boot Swagger2 集成REST ful API 生成接口文档 原文 简介 由于Spring Boot 的特性,用来开发 REST ful 变得非常容易,并且结合 Swagg ...
- 关于ASP.NET Web Api的HelpPage文档注释问题
关于ASP.NET Web Api的HelpPage文档注释问题 以前我用微软的HelpPage来自动生成的webAPI帮助文档.在使用了一段时间后发现只能显示Controller上面写的注释文档内容 ...
- net core Webapi基础工程搭建(三)——在线接口文档Swagger
目录 前言 Swagger NuGet引用第三方类库 别急,还有 没错,注释 小结 前言 前后分离的好处,就是后端埋头做业务逻辑功能,不需要过多考虑用户体验,只专注于数据.性能开发,对于前端需要的数据 ...
- 使用swagger作为restful api的doc文档生成——从源码中去提取restful URL接口描述文档
初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情.也许多点,也许少点.甚至,接口总是需要适应新需求的,修改了,增加了,这份 ...
随机推荐
- Microsoft.Office.Interop.Excel 导出Excel
; ; /// <summary> /// 使用 Excel.dll 导出 Excel /// </summary> /// <param name="list ...
- npm安装和Vue运行
一.开始: 下载地址:http://nodejs.cn/download/ 下载安装: 直到 二.打开CMD,检查是否正常 在安装目录里新增两个文件夹 然后运行命令:如下图: npm config s ...
- xt
using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; usin ...
- 【slenium专题】Webdriver同步设置
Webdriver同步设置常用等待类主要如下图所示 注:support.ui包内类主要实现显性等待功能,timeouts()内方法主要实现隐性等待功能 一.线程休眠 Thread.sleep(long ...
- ElasticSearch学习总结(二):ES介绍与架构说明
本文主要从概念以及架构层面对Elasticsearch做一个简单的介绍,在介绍ES之前,会先对ES的"发动机"Lucene做一个简单的介绍 1. Lucene介绍 为了更深入地理解 ...
- python del 方法的使用
在Python 的自带函数中 del 函数是一个非常特殊但是又非常使用的函数 my_list = [1,2,3] my_dict = {"name":"lowman&qu ...
- request.getParameter("name")获取参数为null和空字符串的区别
1.获取到的值为空字符串 当url里有name属性,但是没有值的时候,后台用request.getParameter("name")获取到的是空字符串 2.获取到的值为null 当 ...
- WebDriverAPI(8)
判断页面元素是否存在 测试网址 http://www.baidu.com Java语言版本API实例 @Test public void testIsElementPresent(){ driver. ...
- Android学习之一
- 关于冒泡排序的Java代码实现
一.排序算法的历史: 排序算法的发展历史几乎和计算机的发展历史一样悠久,而且直到今天,世界范围内依然有计算机科学家正在研究着排序的算法,由此可见排序算法的强大魅力. 我们现在介绍的排序算法都是前任 ...