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

前言

公司一直采用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 条评论
登录 后参与评论

扫码关注云+社区

领取腾讯云代金券