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 即可访问及查阅生成的文档；

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

猜你喜欢