使用第三方提供的swgger ui 可有效提高 web api 接口列表的阅读性,并且可以在页面中测试服务接口。

但本人在查阅大量资料并进行编码测试后,发现大部分的swagger实例并不能有效运行。例如如下两个网址:http://www.cnblogs.com/caodaiming/p/4156476.html 和 http://bitoftech.net/2014/08/25/asp-net-web-api-documentation-using-swagger/。经过本人的一番折腾,最终发现,原来是由版本的差异导致的(以上两个例子在4.2.0版本下运行成功,读者可自行测试)。哎,要是这些作者能够标出插件包的版本,真能省下很多功夫。

目前Swashbuckle的最新稳定版本为5.2.1版。这个版本的编码方式与4.2.0版本有一定差异,本文也以5.2.1版本为例进行说明。

注:本文使用OWIN来自寄宿(self-host) web api,不清楚的读者可参考:http://www.asp.net/web-api/overview/hosting-aspnet-web-api/use-owin-to-self-host-web-api。

1、新建一个控制台应用程序OwinConsoleApp。Nuget分别添加Swashbuckle(5.2.1版本)和Microsoft.AspNet.WebApi.OwinSelfHost。添加Swashbuckle时,会在项目中自动添加App_Start文件夹和一个文件名为“SwaggerConfig”的文件。

2、新建一个StudentController文件, 代码如下:

  1. using System;
  2. using System.Collections.Generic;
  3. using System.Web.Http;
  4. using System.Web.Http.Description;
  5. namespace OwinConsoleApp
  6. {
  7. /// <summary>
  8. /// 学生信息
  9. /// </summary>
  10. public class StudentController : ApiController
  11. {
  12. /// <summary>
  13. /// 得到所有的学生信息
  14. /// </summary>
  15. /// <returns></returns>
  16. public IEnumerable<string> Get()
  17. {
  18. return new List<string>() { "student A", "student B" };
  19. }
  20. /// <summary>
  21. /// 根据学生编号得到学生信息
  22. /// </summary>
  23. /// <param name="Id">学生编号</param>
  24. /// <returns></returns>
  25. public string Get(int Id)
  26. {
  27. return "学号:" + Id;
  28. }
  29. /// <summary>
  30. /// 添加学生
  31. /// </summary>
  32. /// <param name="studentModel">学生实体</param>
  33. /// <remarks>添加一个新的学生</remarks>
  34. /// <response code="400">Bad request </response>
  35. /// <response code="500">Internal Server Error</response>
  36. public void Post(String studentModel)
  37. {
  38. }
  39. /// <summary>
  40. /// 修改学生信息
  41. /// </summary>
  42. /// <param name="Id">学生编号</param>
  43. /// <param name="studentModel">学生实体</param>
  44. [ResponseType(typeof(string))]
  45. [ActionName("UpdateStudentById")]
  46. public void Put(int Id, string studentModel)
  47. {
  48. }
  49. /// <summary>
  50. /// 删除学生信息
  51. /// </summary>
  52. /// <param name="Id">学生编号</param>
  53. public void Delete(int Id)
  54. {
  55. }
  56. }
  57. }

3、修改SwaggerConfig文件如下:

  1. using System.Linq;
  2. using System.Web.Http;
  3. using WebActivatorEx;
  4. using OwinConsoleApp;
  5. using Swashbuckle.Application;
  6. [assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]
  7. namespace OwinConsoleApp
  8. {
  9. public class SwaggerConfig
  10. {
  11. public static void Register(HttpConfiguration config)
  12. {
  13. config.EnableSwagger(c =>
  14. {
  15. c.SingleApiVersion("v1", "");
  16. c.IncludeXmlComments(GetXmlCommentsPath());
  17. c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
  18. })
  19. .EnableSwaggerUi();
  20. }
  21. private static string GetXmlCommentsPath()
  22. {
  23. return System.String.Format(@"{0}\Swagger.XML", System.AppDomain.CurrentDomain.BaseDirectory);
  24. }
  25. }
  26. }

4、新建一个Startup文件,代码如下:

  1. using Owin;
  2. using Microsoft.Owin;
  3. using System.Web.Http;
  4. using Swashbuckle.Application;
  5. [assembly: OwinStartup(typeof(OwinConsoleApp.Startup))]
  6. namespace OwinConsoleApp
  7. {
  8. public class Startup
  9. {
  10. public void Configuration(IAppBuilder appBuilder)
  11. {
  12. // Configure Web API for self-host.
  13. HttpConfiguration config = new HttpConfiguration();
  14. config.Routes.MapHttpRoute(
  15. name: "DefaultApi",
  16. routeTemplate: "api/{controller}/{id}",
  17. defaults: new { id = RouteParameter.Optional }
  18. );
  19. SwaggerConfig.Register(config);
  20. appBuilder.UseWebApi(config);
  21. }
  22. }
  23. }

5、修改program程序,代码如下:

  1. using System;
  2. using Microsoft.Owin.Hosting;
  3. namespace OwinConsoleApp
  4. {
  5. class Program
  6. {
  7. static void Main(string[] args)
  8. {
  9. string baseAddress = "http://localhost:9000/";
  10. // Start OWIN host
  11. using (WebApp.Start<Startup>(url: baseAddress))
  12. {
  13. Console.WriteLine("OWIN SERVICE OPEN!");
  14. Console.Read();
  15. }
  16. Console.ReadLine();
  17. }
  18. }
  19. }

6、右键项目属性,在属性的“生成”中设置输出文档:


注:这里的XML文件路径和文件名应与SwaggerConfig文件中的配置保持一致。

7、管理员身份运行程序。在浏览器中输入如下地址:http://localhost:9000/swagger,显示如下页面:


点击相应的服务,在显示的框中输入对应的信息,再点击“Try it out!”,即可成功调用服务,并可查看返回的结果。

后话:搞了两天,终于把swagger搞出来了,当初就是在版本的差异上浪费了太多时间。写此文章,与和我有相同经历的人共勉。文中若有纰漏,还请指出。

ASP.NET Web Api 2 接口API文档美化之Swagger的更多相关文章

  1. Web Api 自动生成帮助文档

    Web Api 自动生成帮助文档   新建Web Api项目之后,会在首页有API的导航菜单,点击即可看到API帮助文档,不过很遗憾,Description 是没有内容的. 怎么办呢? 第一步: 如果 ...

  2. 后端编写Swagger接口管理文档

    Swagger接口管理文档 访问接口文档的网页:http://localhost:8080/swagger-ui/index.html 导入依赖 <dependency> <grou ...

  3. 支付宝接口使用文档说明 支付宝异步通知(notify_url)与return_url.

    支付宝接口使用文档说明 支付宝异步通知(notify_url)与return_url. 现支付宝的通知有两类. A服务器通知,对应的参数为notify_url,支付宝通知使用POST方式 B页面跳转通 ...

  4. Java实现web在线预览office文档与pdf文档实例

    https://yq.aliyun.com/ziliao/1768?spm=5176.8246799.blogcont.24.1PxYoX 摘要: 本文讲的是Java实现web在线预览office文档 ...

  5. (转)WEB页面导出为Word文档后分页&横向打印的方法

    <html>    <HEAD>        <title>WEB页面导出为Word文档后分页&横向打印的方法 </title>    < ...

  6. Web 前端 UI 组件库文档自动化方案 All In One

    Web 前端 UI 组件库文档自动化方案 All In One 需求 自动化 动态 好用 markdown element-ui 中示例和说明按照一定规则写在md文件中,调用md-loader将md文 ...

  7. 容器环境下如何将NuGet包XML文档添加到Swagger

    容器环境下将NuGet包XML文档添加到Swagger 在.NET Core项目开发过程中,为了实现代码复用,我们将可以重复使用的部分拆分成一个个小的NuGet包.这些NuGet包可以在其他系统中复用 ...

  8. Web Api 2 接口API文档美化

    使用用第三方提供的swgger ui 帮助提高 web api 接口列表的阅读性,并且可以在页面中测试服务接口. 运行程序如下: 注意:在IE中必须输入红色部分. 并且可以对方法进行测试. 在开发we ...

  9. Web API 自动生成帮助文档并使用Web API Test Client 测试

    之前在项目中有用到webapi对外提供接口,发现在项目中有根据webapi的方法和注释自动生成帮助文档,还可以测试webapi方法,功能很是强大,现拿出来与大家分享一下. 先看一下生成的webapi文 ...

随机推荐

  1. HTTP协议04-返回状态码

    状态码职责是在客户端向服务器端发送请求时候,描述返回的请求结果.借助状态码,用户可以知道服务器是否正常处理了请求,还是出错了. 状态码的类别   类别 原因短语 1XX Informational(信 ...

  2. mysql数据库基于linux的安装步骤及数据库操作

    一.数据库安装 Ubuntu上安装MySQL非常简单只需要几条命令就可以完成. sudo apt-get install mysql-server sudo apt-get isntall mysql ...

  3. 解决Windows 10笔记本接显示器分屏后没有声音的问题

    Windows 10 版本号:17763.292 1.首先右键点击任务栏托盘中的[扬声器]图标,选择[声音],如下图所示. 2.选择[播放],然后选择[扬声器],再点击[设为默认值],如下所示. 3. ...

  4. Docker的离线安装

    由于公司需要离线部署Docker,这里将其步骤记录下来. 目标环境Centos7.2. 由于目标环境为公司内网,首先尝试在https://download.docker.com/linux/cento ...

  5. 使用Navicat为MySQL建立定时任务

    1.编写好每个小时需要指定的sql语句,我一般都是编写的一个update SQL,也可以编写好一个函数存储过程 2.点击事件,可能回看到一些事件列表,然后点击上方的“新建事件”,会打开一个事件定义框( ...

  6. mgo 的 session 与连接池

    简介 mgo是由Golang编写的开源mongodb驱动.由于mongodb官方并没有开发Golang驱动,因此这款驱动被广泛使用.mongodb官网也推荐了这款开源驱动,并且作者在github也表示 ...

  7. 常用的ORM框架

    现在,很多项目使用ORM的框架构架实现数据持久层,下面列举一些常用的ORM框架有,后续分节介绍. Java:Hibernate和Mybatis(前身iBatis) .Net:EF6与EFCore.Da ...

  8. Thread Synchronization Queue with Boost

    介绍:当开发一个多线程程序时,同步是一个很大的问题.如果你的程序需要数据流包,那么用队列是个好办法. 你可以在 http://www.boost.org/ 发现 boost 库和文档,从它的网站可以看 ...

  9. List集合三种遍历方法

    List<String> list = new ArrayList<String>();list.add("aaa");list.add("bbb ...

  10. Confluence 6 尝试从 XML 备份中恢复时解决错误

    错误可能是因为数据库突然不可访问而产生.也有可能是你备份文件有问题,你需要找到你 XML 备份文件中违反数据库规定的记录修改这个记录后再创建一个新的 XML 备份: 在实例开始恢复的时候,请按照下面的 ...