Asp.Net WebApi Swagger终极搭建

2021-04-15 05:28

阅读：597

标签：程序前后端分离 play ase pipeline xxxx head private 拷贝

关于为什么用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,Swagger.Net.UI

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

　　8：修改SwaggerConfig.cs

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

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

　　9：右键项目NuGet——》已安装——》搜索Swagger，卸载Swagger.Net.UI——》选项勾选强制卸载，点击卸载。卸载Swagger.Net

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

Swagger进阶

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

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

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

　　3：注释的用法

　　注释的用法，在API接口中"///"三斜杠注释的summary为接口名注释，summary下回车为备注，注意每个字段的注释必须要全面，否则无法显示完全

　　参考代码如下

/// 
        /// 角色 分页列表
        /// 
        /// 
        /// Code返回值说明：
        /// 
        ///         错误码地址：http://xxxx.com/
        /// 
        /// 
        /// 分页查询条件
        /// 
        [HttpGet, Route("api/ClientRoles")]
        public OutputModel>> GetRoleList([FromUri]PagingInputModel conditionModel)
{
    return null;

}