• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

ASP.NET WebApi 使用Swagger生成接口文档

原作者: [db:作者] 来自: [db:来源] 收藏 邀请

前言

公司一直采用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.增加了写注释的好习惯

 


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
热门话题
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap