Webapi文档描述-swagger优化

1、前言

最近作的项目使用WebApi，采起先后端分离的方式，后台提供API接口给前端开发人员。这个过程当中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员，最初打算使用word、Xmind思惟导图方式进行交流，实际操做中却不多动手去写。为了解决这个问题，特地在博客园搜索了一下api接口文档生成的文章，引发我注意的有如下两种方案。

• 微软自带的Microsoft.AspNet.WebApi.HelpPage
• Swagger（丝袜哥）

可是在使用过程当中微软自带的没有Swagger直观，所以采用了第二种方案Swagger。

2、问题

在使用swagger的过程当中，产生了一些小问题，例如：汉化、查询、控制器备注。
在博客园当中找到了相关的解决方式，可是汉化、控制器备注会产生二次请求的问题，尤为在接口比较多的状况下，仍是比较慢的。所以产生了修改swagger-ui和Swashbuckle源码的念头。

3、效果图

3.1 汉化效果

3.2 控制器注释以及接口数量统计

3.3 查询

4、如何使用

4.1 建立Webapi项目解决方案

4.2 引用SwashbuckleEx nuget包

SwashbuckleEx和SwashbuckleEx.Core这两个包

4.3 添加接口注释

完成上面2部运行项目，能够看到接口描述已经生成，浏览地址http://xxxx/swagger。可是没有接口的注释，下面添加接口注释。

4.3.1 项目属性->勾选生成xml文档文件

注：若是实体与Api库分开，那么须要在实体库也勾选上生成xml文件，并设置文件名称（默认名称便可）。

4.3.2 修改SwaggerConfig.cs文件

c.SingleApiVersion("v1", "xxx");
c.IncludeXmlComments(string.Format("{0}/bin/xxx.Api.XML", AppDomain.CurrentDomain.BaseDirectory));

给接口添加注释，便可看到参数与方法描述了。

4.3.3 配置Web.config文件

有园友提出使用Nuget包后，展现是空的，所以看了下，须要配置一下如下的内容便可。

<system.webServer>
    <modules runAllManagedModulesForAllRequests="true">
        <remove name="WebDAVModule" />
    </modules>
</system.webServer>

5、源码地址

Github：https://github.com/jianxuanbing/SwashbuckleEx.git

6、总结

修改Swashbuckle源码过程当中，踩的坑仍是比较多的，这个后续开一篇文章进行说明实现上述的功能。
有了汉化、控制器注释、接口数量统计、查询，加快的先后端开发的对接。

7、参考

• ASP.NET WebApi 文档Swagger中度优化
• ASP.NET WebApi 文档Swagger深度优化