前言

公司一直采用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. Example004自动关闭的广告窗口

    <!-- 实例004自动关闭的广告窗口--> <!-- 3秒后关闭 --> <body onload="window.setTimeout('window.cl ...

  2. ajax来判断用户是否登录与添加

    首先在用ajax之前,先说一下JSON: JSON:javascript object notation   js对象标记 对于json,我们只需要知道如何定义json?如何输出?怎么遍历? 1.定义 ...

  3. ARP欺骗分析

    (作者原创,欲转载请说明出处)1.arp介绍    arp:地址解析协议;将IP地址映射为MAC地址.2.为什么要有arp    平时上网我们都知道要有一个IP地址才能上网,那arp用来干嘛的呢?如果 ...

  4. 如何在docker配置asp.net core https协议

    本文参考自<Step by step: Expose ASP.NET Core over HTTPS with Docker> 自从微软发布.net core以来,就在许多社区掀起了讨论, ...

  5. 解决QZ-SDK静态库libRPToolLib.a中avfoundation.o文件和kxMovie依赖的ffmpeg静态库libavdevice.a函数重复定义的问题

    解决QZ-SDK静态库libRPToolLib.a中avfoundation.o文件和kxMovie依赖的ffmpeg静态库libavdevice.a函数重复定义的问题 在原来项目中导入全志v3相机的 ...

  6. vue2.0设置proxyTable使用axios进行跨域请求

    这里请求的是知乎日报的api,由@izzyleung这位大神提供的,这是github地址. 在vue-cli构建的项目中先安装axios npm install axios -S 这里暂不考虑用vue ...

  7. MYSQL的日志与备份还原

    一.错误日志 当数据库出现任何故障导致无法使用时,第一时间先去查看该日志 1.服务器启动关闭过程中的信息 2.服务器运行过程中的错误信息 日志存放路径,可以通过命令查看: 日志文件命名格式:host_ ...

  8. C++第二篇--访问控制

    C++第二篇--访问控制 1. 引入 上一篇博文中从结构体引到了类,类当中不仅有数据成员还有一些函数,这些函数被称为成员函数.今天介绍新的内容,类当中的访问控制. 2. 访问控制 当你不添加任何声明, ...

  9. Hybris商品图片导入与压缩有关的配置

    1.   在电脑上安装 ImageMagick 软件(windows平台还需要安装VC++),下载路径:http://www.imagemagick.org/script/download.php#w ...

  10. JavaScript获取鼠标位置的三种方法

    在一些DOM操作中我们经常会跟元素的位置打交道,鼠标交互式一个经常用到的方面,令人失望的是不同的游览器下会有不同的结果甚至是有的游览器下没结果,这篇文章就鼠标点击位置坐标获取做一些简单的总结. 获取鼠 ...