Asp.Net WebApi Swagger终极搭建

【PS：原文手打，转载说明出处，博客园】

关于为什么用Swagger

　　目前稍微有点规模的公司，已经从原先的瀑布流开发到了敏捷开发，实现前后端分离，为此后端工程师只关注写好Api即可，那程序员最讨厌的就是写Api文档了，故而产生了Swagger。

Swagger原理

　　Swagger就是利用反射技术遍历所有Api接口，并且从xml文件中读取注释，在利用Swagger内置的模板组合html显示至客户端实现接口可视化，并且可调用。

Asp.net WebApi Swagger集成

　　1：vs2017，新建web项目，选择WebApi

　　2：删除Views、Scripts、Models、fonts、Content、Areas目录

　　3：删除RouteConfig.cs、FilterConfig.cs、BundleConfig.cs

　　4：删除HomeController.cs

　　5：Global.asax中删除异常代码

　　6：nuget搜索Swagger,安装 Swashbuckle

　　7：右键项目——》属性——》生成——》输出——》勾选XML文档文件——》保存

　　8：修改SwaggerConfig.cs

　　　　新增方法，释放c.IncludeXmlComments(GetXmlCommentsPath());的注释（注意：例如返回值为对象，然后又不在同一个项目，则需要多次调用）

private static string GetXmlCommentsPath()
{
      return System.String.Format(@"{0}\bin\{项目名称}.XML",
                System.AppDomain.CurrentDomain.BaseDirectory);
}

　　9：然后在url地址中:例如：http://localhost:port/swagger即可

Swagger进阶

　　1：当有dto项目时，此时dto也需要把注释打到客户端，注意dto项目也参考上面第7点生成xml文件，复制第8点的方法

　　2：Swagger新增Header信息，在上方注释的地方加入：c.OperationFilter<HttpHeaderFilter>(); 拷贝下方代码

public class HttpHeaderFilter : IOperationFilter
        {
            public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
            {
                
                if (operation.parameters == null)
                    operation.parameters = new List<Parameter>();
                var filterPipeline = apiDescription.ActionDescriptor.GetFilterPipeline(); //判断是否添加权限过滤器
                var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Instance)
                    .Any(filter => filter is ErpFilterAttribute); //判断是否允许匿名方法 
                //var allowAnonymous = apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any();
                if (isAuthorized)
                {

                    operation.parameters.Add(new Parameter
                    {
                        name = "AppId",
                        @in = "header",
                        description = "应用ID（机构编号）",
                        required = false,
                        type = "string"
                    });

                    operation.parameters.Add(new Parameter
                    {
                        name = "Version",
                        @in = "header",
                        description = "版本号",
                        required = false,
                        type = "string"
                    });

                    operation.parameters.Add(new Parameter
                    {
                        name = "Ts",
                        @in = "header",
                        description = "时间戳",
                        required = false,
                        type = "string"
                    });

                    operation.parameters.Add(new Parameter
                    {
                        name = "Lang",
                        @in = "header",
                        description = "语言包",
                        required = false,
                        type = "string"
                    });

                    operation.parameters.Add(new Parameter
                    {
                        name = "Sign",
                        @in = "header",
                        description = "签名",
                        required = false,
                        type = "string"
                    });

                    return;
                }
            }
        }

View Code