Asp.Net MVC添加Swagger接口文档方法

 

　　 公司最近的项目使用mvc+webapi，采取前后端分离的方式，后台提供API接口给前端开发人员。这个过程中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员,之前一直使用的是word文档方式进行交流，效率低下而且不利于维护。为了解决这个问题，经过一番研究，引起我注意的有两种方案。1.微软自带的Microsoft.AspNet.WebApi.HelpPage  2.swagger（我比较喜欢戏称为“丝袜哥”）

最先尝试的是微软自带的方案，由于界面实在是比较一般，于是转向了第二种方案,经过大半天大捣鼓，最终效果如下：

1.列出所有API控制器和控制器描述

 

 

2.直观的接口测试

达到这几点目标，已经满足项目使用。

 

使用swagger

　　1.创建webapi项目解决方案

　　2.引用swagger nuget包

　　引入Swashbuckle一个包即可，有些教程说要引入和Swagger.Net.UI，其实功能重复了（后面会解释）。

引入后，项目App_Start下会多一个文件：

　　 3.添加接口注释

　　完成上面三步运行项目，可以看到接口描述已经生成，浏览地址http://xxx//swagger/ui/index。但是没有接口的注释，当时决定引入Api管理工具就是看中了注释功能，下面添加接口注释

　　

 

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

　　

　　修改SwaggerConfig文件（需要将生成的xml文件拷贝至app_data文件夹中）

public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "BI_MVC");
                        c.IncludeXmlComments(GetXmlCommentsPath());
                        c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
                        c.UseFullTypeNameInSchemaIds();

                    })
                .EnableSwaggerUi(c =>
                    {
                        c.DocumentTitle("BI_MVC");
                       // c.InjectJavaScript(thisAssembly, "BI_MVC.App_Start.ExtensionSwagger.Js.SwaggerHelp.js");

                    });
        }
        private static string GetXmlCommentsPath()
        {
            //1.需要和程序集=》属性=>生成=》输出xml的名称一致。
            //2.将xml文件拷贝至app_data文件夹中
            return string.Format("{0}/App_Data/BI_MVC.XML", System.AppDomain.CurrentDomain.BaseDirectory);
        }

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

 

汉化及问题解决

经过上面的操作，已经完成了所需功能。但是还有几点问题需要完善

     1.界面的说明都是英文的需要进行汉化

     2.控制器没有描述

     3.接口过多每次生成速度比较慢

1.汉化步骤

在SwaggerConfig配置文件中有这么一段代码

     .EnableSwaggerUi(c =>
                    {
                      c.InjectJavaScript(thisAssembly, "BI_MVC.App_Start.ExtensionSwagger.Js.SwaggerHelp.js");

                    });

这段代码的作用是向页面输出引用Swashbuckle.Dummy.SwaggerExtensions.testScript1.js文件，或许会疑问js文件路径为什么这么奇怪。那是因为Swagger将资源文件都嵌入到dll中了，我们常用的资源文件都是以内容的方式放在项目中的，我们也可以以嵌入的资源方式引入到项目中

这也是上面不引入Swagger.Net.UI,页面也能正常出来的原因。资源文件都被打包到dll中了，使用反编译工具reflector。来反编译一下Swashbuckle.Core.dll

弄清楚了实现原理，现在来实现汉化。添加自己的中文语言包，和转换js，实现逻辑参考swagger源码。

 

上面汉化的js中的方法_setControllerSummary通过读取ControllerDesc属性设置了控制器的描述，至此项目可以无忧使用接口描述文档。

3.action 方法名称相同处理

 

根据错误提示 很快发现 某位大神 同样的接口名 传递了不同参数，导致了这个错误，解决方式：

c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());

4.一个Controller不支持多个Get/Post请求问题，修改WebApiConfig.cs

 

5.Date时间类型不对生成Json格式不对的问题

WebApi自带json序列化对遇到时间日期字段的时候，到前端获取的格式总是为“ 2016-07-14T15:32:44”，中间总是会带一个T,显然不是很友好，解决方案如下：

6swagger 问题2.序列化出来的JSON NULL 值处理。

先上图

等了好半天 一直不出来 打开F12一看原来有错，万能的网友帮了我，原来问题出在http://localhost:58303/swagger/docs/v1这个JSON资源上面，

序列化出来的JSON，包含了为NULL的字段，导致swagger-ui-min-js出现异常。

进一步分析是因为我项目使用的newtonsoft.json这个库的配置导致，应该忽略为NULL的字段，

对应解决办法如图： settings.NullValueHandling = NullValueHandling.Ignore;

总结：

规范化api的编写和注释，以及标准化文档，对于团队的开发效率有很大的提升，也有利于项目的维护。使用在线接口文档后，方便前后端工程师沟通，测试人员测试只需要在页面输入参数，点击调用就可以看到调用结果。