Swagger 是一套 API 交互文档产生器,使用 HTML 与 Javascript 所编写的,与之前所介绍的 ASP.NET Web API Help Page 不同的是,Swagger 是一套 Open Source Software,支持了现在许多的 REST API,之所以会说这是一个交互的文档,除了显示 API 输出入规格外,也能够让使用者即时的在 Swagger UI 界面上进行操作,立刻就能看到执行结果。
这一篇将会简单说明如何在一个 ASP.NET Web API 项目里加入 Swagger 功能。
Swagger
http://swagger.io/
如果还不太晓得 Swagger 有什么功能以及可以做什么事情,我建议可以先到官网的 Live Demo 网站看看,看一看、点一点、操作几个功能,应该就可以知道了,
http://petstore.swagger.io/
在 ASP.NET Web API 项目里安装使用
那么在 ASP.NET Web API 项目里要怎么使用呢?
其实可以不用那么辛苦的从头安装 Swagger,已经有人开发好 NuGet 套件,只要从 NuGet 安装到 ASP.NET Web API 项目里,然后稍做修改就可以了,基本的安装使用并不会太复杂,只要跟着以下的步骤作就可以了。
范例沿用前一篇“ASP.NET Web Api - Help Page”文章里的范例,在项目里透过 NuGet 安装以下两个 Packages,分别是:Swashbuckle 和 Swashbuckle.Core
装了 Swashbuckle 就会把 Swashbuckle.Core 一并安装进来,
安装好 Swashbuckle 与 Swashbuckle.Core 之后,要检查看看下面的文件是不是有建立,
App_Start/SwaggerConfig.cs
一定要做的就是别忘了 Controller 与 Action 方法要加上 Summary
另外千万别忘了在项目属性里要勾选建置时输出“XML 文档文件”
再来最重要的就是修改 SwaggerConfig.cs 的内容,在程序的第 99 行,将这一行给反注解,
不过把这一行给反注解之后却会出现错误,
这是因为还没有实践 GetXmlCommentsPath() 方法,这个方法是要提供 XML Document 文件的路径,这么一来 Swagger 才能够正确的显示 Controller 与 Action 方法的相关资讯,
万事具备之后就可以执行网站了,要查看 API 服务的 Swagger 文档页面,在网址根目录后面加上 Swagger 就可看到,例如:http://localhost:60900/Swagger
线上执行后显示回传结果
这一篇只是做简单的介绍,如果你有兴趣可以在进阶研究 Swagger,但因为我们是开发 ASP.NET Web Api 并且是使用 Swagger for Web API - Swashbuckle,所以建议各位要进阶研究的对象应该是“Swashbuckle”,其实有很多很进阶的修改与设定可以玩的。
Postman 与 Swagger 的差异
- Postman 适合开发人员的统整管理,并且可以直接导出 C# (RestSharp) 的程序,并且直接放在程序里使用
- Swagger 适合即时开发的使用,甚至是提供给非开发人员测试使用
- 建议两种同时使用,开发人员在开发时的测试可以使用 Swagger 马上做测试,完成开发后可以到 Postman 之后去对系统做测试
参考连结
http://swagger.io/
http://petstore.swagger.io/
https://github.com/domaindrivendev/Swashbuckle
KingKong Bruce记事: ASP.NET Web API 文档产生器(2) - Swagger
以上
分享
原文:大专栏 ASP.NET Web API 文档产生器 - 使用 Swagger