使用Swagger实现webapi接口自动化文档生成

         这里是实现自动化api妥当的生成，在网上看了不少swagger的文档，可能都是在为实现接口时直接使用的swagger，其实步骤差很少，可是更加详细的我还没看到，又或者说，我看着文档来的时候仍是出错啦，绕了很大的弯，以前有听过要用这个，可是仍是用过。接下来总结下我此次在使用过程当中的步骤及一些问题。

        在接口已经成型的基础上集成swagger，实现了接口文档的自动化生成，相对于开发来讲节约了写文档的大部分时间，无疑是一件莫大的好事情。接下来总结下这个过程：

         1、在现有Api的基础上添加Nuget包的引用（这里简述下现有api，不必定是webapi项目，要看接口实如今哪里，能够是类库，也能够是项目webapi等），有2个包，一个是Swagger.Net.UI，一个是Swashbuckle，以下图所示：

          （1）、Swagger.Net.UI的添加引用：

          

          （2）、Swashbuckled的添加引用

          

            这里的版本是4.5.2的版本，可能在4.0版本上就不同啦，这里我没有尝试。。。

 

          2、安装成功后会有新增的文件以下所示：

                                               

             上面的由于前端的ui等都集成在dll中，因此SwaggerUI、App_Start下的SwaggerNet类均可以删除 ，而后主要是配置SwaggerConfig.cs文件。      

 

           3、在设置的启动项目下生成XML文件，步骤以下：

            例如：我目前项目中有去实现接口的web项目，我就选择此“web项目”->“属性”->“生成”->勾选XML文件文件，以下如所示：

            

           而后点击保存，便可在bin文件下面找到此文件，能够自行去看下。

 

            四、修改App_Start文件夹下的SwaggerConfig文件

             （1）、添加注释

             打开App_Start文件夹下的SwaggerConfig文件，在方法Register把注释过的c.IncludeXmlComments(GetXmlCommentsPath());放开，而后在此类中增长方法GetXmlCommentsPath来获取生成文件的位置便可（又或者以下图，直接取XML文件也可）。而下面的路径是上面生成的XML文件的路径，而放开注释的那段代码实现了对XMl文件的读取，即添加注释，方法的实现以下：

               

             （2）、隐藏不须要的接口（便可以添加剧复的接口）

             

             上面就是全部用到的，关于处理接口的代码，c.DocumentFilter<HiddenApiFilter>();这个是为了实现过滤本身不须要的接口来设置的

            HiddenApiFilter这个类的实现以下：

    /// <summary>  
    /// 隐藏接口，不生成到swagger文档展现  
    /// </summary>  
    [System.AttributeUsage(System.AttributeTargets.Method | System.AttributeTargets.Class)]

    public partial class HiddenApiAttribute : System.Attribute { }
    public class HiddenApiFilter : IDocumentFilter
    {
        /// <summary>  
        /// 重写Apply方法，移除隐藏接口的生成  
        /// </summary>  
        /// <param name="swaggerDoc">swagger文档文件</param>  
        /// <param name="schemaRegistry"></param>  
        /// <param name="apiExplorer">api接口集合</param>  
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        {
            foreach (ApiDescription apiDescription in apiExplorer.ApiDescriptions)
            {
                if (Enumerable.OfType<HiddenApiAttribute>(apiDescription.GetControllerAndActionAttributes<HiddenApiAttribute>()).Any())
                {
                    string key = "/" + apiDescription.RelativePath;
                    if (key.Contains("?"))
                    {
                        int idx = key.IndexOf("?", System.StringComparison.Ordinal);
                        key = key.Substring(0, idx);
                    }
                    swaggerDoc.paths.Remove(key);
                }
            }
        }

             这个类为了方即可以直接在swaggerconfig类中，以下图所示：

              

             最后一步就是在咱们不须要显示的接口类或者类内方法上面添加以下过滤器以下：

                           

 

            5、修改App_Start文件夹下的SwaggerNet文件，注释以下图的代码（我不知道为何，若是不注释会报错的）：

              

               注释代码以下：

              

             以上就是实现自动化的所有步骤，在地址栏中输入地址以下：便可看到以下的界面：

              

                过程就是这样的，但是作个小demo练习，我这个是直接在项目中添加啦。