前言

公司一直采用Word文档方式与客户端进行交流。随着时间的推移,接口变的越来越多,文档变得也很繁重。而且一份文档经常由多个开发人员维护,很难保证文档的完整性。而且有时写完代码也忘了去更新文档,为了这些小事经常受客户端同事鄙视。

于是带着问题去查找解决方案,在网上一通乱搜后查找出以下两个工具:AspNet.WebApi.HelpPage,Swagger。

细细比较最终选择 Swagger ,因为优点实在太多,具体可网上自行搜索,在这里就不在赘述。

实现

1.引用NuGet包

           

2.设置项目属性,勾选生成XML注释文件

     

3.修改SwaggerConfig文件

  3.1添加读取XML注释文件方法    

 protected static string GetXmlCommentsPath(string name)
        {
            return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
        }

  3.2修改SwaggerConfig配置

//设置接口描述xml路径地址
 c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));

4.效果展示

项目启动后,在域名后输入Swagger即可。如:http://localhost:65199/swagger/就会出现如下界面

 

点击试一下可在线调试接口。

  

5.注释详解


注释标签不同,UI呈现位置也不一样。常见的有<summary>、<remarks>、<response>

如果响应是一个对象或对象列表,可在当前项目下创建一个ViewModel,并将ViewModel添加到方法头部。如:

[ResponseType(typeof(ViewModel))]

UI效果:

总结

Swagger给我带来的两大好处是:1.以后再也不用写Word文档了,2.增加了写注释的好习惯

ASP.NET WebApi 使用Swagger生成接口文档的更多相关文章

  1. ASP.NET WebAPI使用Swagger生成测试文档

    ASP.NET WebAPI使用Swagger生成测试文档 SwaggerUI是一个简单的Restful API测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON配置显示API .项目 ...

  2. asp.net core 使用 swagger 生成接口文档

    参考地址:http://www.cnblogs.com/daxnet/p/6181366.html http://www.jianshu.com/p/fa5a9b76f3ed 微软参考文档:https ...

  3. WebAPI使用Swagger生成接口文档

    开发工具:VS2017 版本15.7.1 新建项目,选择空模板,下面只勾选WebAPI 配置Web.config <system.webServer> 节点改为 <system.we ...

  4. ASP.NET WEBAPI 使用Swagger生成API文档

    一.安装 新建一个没有身份验证的mvc项目 - SwaggerMvc5Demo,然后添加一个名为Remote(自定义)且包含基础读写(不想手写)的ApiController   开源地址:https: ...

  5. webapi 利用webapiHelp和swagger生成接口文档

    webapi 利用webapiHelp和swagger生成接口文档.均依赖xml(需允许项目生成注释xml) webapiHelp:微软技术自带,仅含有模块.方法.请求-相应参数的注释. swagge ...

  6. .net core 使用 swagger 生成接口文档

    微软参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs= ...

  7. asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档

    asp.net core中使用Swashbuckle.AspNetCore(swagger)生成接口文档 Swashbuckle.AspNetCore:swagger的asp.net core实现 项 ...

  8. Django使用swagger生成接口文档

    参考博客:Django接入Swagger,生成Swagger接口文档-操作解析 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.总体目标是使客户端和文 ...

  9. Go语言使用swagger生成接口文档

    swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服 ...

随机推荐

  1. linux 小技巧(磁盘空间搜索)

    这里记录一些linux 管理中可能会用到的又容易忘的一些小技巧. linux磁盘写入失败,提示磁盘空间不足.一般都会用df -h 或者df -i看是不是磁盘空间不足或者是inode空间不足.发生这种情 ...

  2. [转]浅谈C++指针直接调用类成员函数

    找了一番之后发现这篇文章讲的很清楚. 传送门

  3. 关于python下安装PIL库遇到的问题及解决办法

    关于python下安装PIL库遇到的问题及解决办法 关于python下安装PIL库遇到的问题及解决办法 :在下面这个网址下载pipllow(a replacement for PIL) www.lfd ...

  4. DOM编程从入门到忘记

    文档对象模型(Document Object Model,DOM)是使用 W3C 定义的 API (Application Program Interface) 来操作 HTML 文档 (此处不局限于 ...

  5. VMwareTools安装失败提示找不到C headers和gcc目录

    在VMware虚拟机上安装好linux系统后,发现往往不能全屏,也不能设置共享文件夹进行文件共享,这时候可以通过安装VMwareTools这个工具来实现文件拖拽.共享和全屏. 安装的过程不再赘述,关键 ...

  6. AJAX跨域的常见方法

    由于在工作中需要使用AJAX请求其他域名下的请求,但是会出现拒绝访问的情况,这是因为基于安全的考虑,AJAX只能访问本地的资源,而不能跨域访问.比如说你的网站域名是aaa.com,想要通过AJAX请求 ...

  7. Java探秘之神秘的字符串String(二)

    不可变性 String可以说是最常用的类型了,即字符串类型,String是常量(final关键词修饰的),他的值不能被创建后更改,因为字符串是不可被改变的,所以可以被用来共享. Java语言为Stri ...

  8. 【ALB学习笔记】基于.NET环境的高频RFID卡读写设备的基本操作案例

    基于.NET环境的高频RFID卡读写设备的基本操作案例 广东职业技术学院  欧浩源 1.引言 RFID高频卡在我们的日常生活中随处可见,是物联网应用中不可或缺的一个重要部分,也是全国职业院校技能大赛& ...

  9. 关于EF 通用增删改查的封装

    1.  Entity Framework是Microsoft的ORM框架,随着 Entity Framework 不断的完善强化已经到达了EF 6.0+ 还是非常的完善的,目前使用的比例相对于其他OR ...

  10. HDU 2255 奔小康赚大钱(带权二分图最大匹配)

    HDU 2255 奔小康赚大钱(带权二分图最大匹配) Description 传说在遥远的地方有一个非常富裕的村落,有一天,村长决定进行制度改革:重新分配房子. 这可是一件大事,关系到人民的住房问题啊 ...