YangJiaoLong的博客

记录、成长、分享、学习

WCF中使用Swagger框架实现接口文档自动化

我有一个梦想,是改变世界,这是很多技术人员的梦想;从小事做起,踏实做人做事,当身边的人或事因为自己能像更好的方向改变或发展的时候,那就是在改变世界,至花甲之时,可能我的梦想也无法实现,但我会一直追逐着他前行。我相信蝴蝶效应。荣耀的背后可这一道孤独。一起学习,一起进步。

做过一定量的接口开发后,会发现文档的书写、整理、实时同步更新、及时测试是一件很耗时的事情,但是得做。
我们可以通过使用Swagger实现接口文档自动化,更好的提高个人或者团队工作效率。
在网上查阅发现有很多使用Swagger的文档,但是几乎没有WCF+Swagger的文档,所以今天书写并整理了一下,保留下来,可供自己、同事、或广大开发小伙伴查阅,一同学习。
下面我们进入正题:

实现WCF+Swagger,从字面上就可以知道,咱们需要具备或完成两个事项:1是实现WCF Rest接口;2是实现Swagger配置及使用

一、实现Wcf Rest API,参见我之前写的博文(见链接)
http://blog.csdn.net/sunshineyang1205/article/details/78864893

二、实现Swagger配置及使用
1、新增Swagger插件
(1)、右键解决方案,点击“管理解决方案的NuGet程序包”选项
这里写图片描述

(2)、搜索SwaggerWcf关键字找到对应插件
这里写图片描述

(3)、单击插件,右边出现项目选择界面,勾选你要安装该插件的项目,然后点击安装,按照提示选择然后安装完成。
这里写图片描述

2、添加全局配置文件,保证服务启动时候也启动Swagger
(1)、在Wcf服务中,新增一个Global.asax文件
这里写图片描述
这里写图片描述
双击打开Global文件,在Application_Start中写入如下代码(注意添加引用)
提一下,添加Activation引用注意,不是添加Activities引用
这里写图片描述

RouteTable.Routes.Add(new ServiceRoute("Service1", new WebServiceHostFactory(), typeof(Service1)));
RouteTable.Routes.Add(new ServiceRoute("api-docs", new WebServiceHostFactory(), typeof(SwaggerWcfEndpoint)));

这里写图片描述

3、针对Swagger对web.config进行配置
(1)、添加Wsagger节点及描述配置,setting中的键对应的值按照语义自行书写即可
这里写图片描述

<configSections>
    <section name="swaggerwcf" type="SwaggerWcf.Configuration.SwaggerWcfSection, SwaggerWcf" />
  </configSections>
  <swaggerwcf>
     <tags>
      <tag name="LowPerformance" visible="false" />
    </tags>
    <settings>
      <setting name="InfoDescription" value="文档标题下方的描述" />
      <setting name="InfoVersion" value="1.0.0.0" />
      <setting name="InfoTermsOfService" value="服务条款" />
      <setting name="InfoTitle" value="文档标题" />
      <setting name="InfoContactName" value="作者" />
      <setting name="InfoContactUrl" value="联系URL" />
      <setting name="InfoContactEmail" value="联系邮箱" />
      <setting name="InfoLicenseUrl" value="许可证地址" />
      <setting name="InfoLicenseName" value="许可证名称" />
    </settings>
  </swaggerwcf>

(2)、在system.serviceModel中添加配置
(a)、添加服务节点

<service name="SwaggerWcf.SwaggerWcfEndpoint">
   <endpoint address="" binding="webHttpBinding" contract="SwaggerWcf.ISwaggerWcfEndpoint"/>
</service>

(b)、设置serviceHostingEnvironment节点的属性: multipleSiteBindingsEnabled=”true” aspNetCompatibilityEnabled=”true”
(c)、设置behavior的子节点webHttp的属性: automaticFormatSelectionEnabled=”true”
这里写图片描述

4、对契约(IService)及接口(Service)实现进行配置
(1)、契约的配置
添加SwaggerWcfPath属性描述:
[SwaggerWcfPath(“标题”, “对该接口的实现的的描述”)]
这里写图片描述
(2)、对实现进行配置
(a)、对实现类新增属性描述
SwaggerWcf的值注意,如wcf服务运行后,接口访问路劲是http:localhost:9000/Service1.svc/{具体接口},那么SwaggerWcf的值为Service1.svc
这里写图片描述

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]
[AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]
[SwaggerWcf("/Service1.svc/")]
[SwaggerWcfResponse(HttpStatusCode.Created, "请求成功的描述")]
[SwaggerWcfResponse(HttpStatusCode.BadRequest, "请求失败 400 的描述", true)]
[SwaggerWcfResponse(HttpStatusCode.InternalServerError, "请求失败 500 的描述", true)]
[SwaggerWcfTag("接口归类1")]

SwaggerWcfTag是接口暴露在文档的一个标记,也是归类
如果接口实现的上无该属性标签,那么该接口不会暴露在文档中
如果有该标签,那么同一个值视为同一类别的接口,会归档在同一个类别中方便展示。
如图三个接口,他们都是“Service1接口”类别的,是因为三个接口的SwaggerWcfTag(“值”)中的值都是“Service1接口”
这里写图片描述

(3)、实体类中新增Description属性标签,这样在接口文档中预览实体的时候才能看到描述
这里写图片描述
效果如图
这里写图片描述

注意:要返回的类及属性,一定要用DataContract和DataMember属性进行描述,如图:
这里写图片描述

这样配置完成,那么WCF Rest 的Swagger使用已经完成。,发布服务,无论你是Self-Host还是搭建在IIS中,服务部署后,
在浏览器中浏览:http://ip:port/api-docs 即可访问及查阅生成的文档;

阅读更多
版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/sunshineyang1205/article/details/78865288
个人分类: 服务 接口
想对作者说点什么? 我来说一句

WCF接口文档生成工具

2018年03月21日 38.94MB 下载

WCF引用服务和直接用接口的区别

2015年07月28日 101KB 下载

没有更多推荐了,返回首页

不良信息举报

WCF中使用Swagger框架实现接口文档自动化

最多只允许输入30个字

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭