.Net WebApi接口之Swagger集成详解

本文详细的介绍了.net从一个新的项目中创建api后集成swagger调试接口的流程！

1、首先我们创建一个MVC项目（VS2012）：

2、然后在项目中的Controllers文件夹中添加API接口文件（WebApi）：

 

创建之后，接口中随便写一个获取信息的方法：

3、集成swagger，通过nuget管理平台添加（右键网站项目-->管理NuGet程序包）：

在打开的NuGet包程序管理界面，联机输入：Swashbuckle 搜索。

 

在打开的NuGet包程序管理界面，联机输入：swagger 搜索。

 

在打开的NuGet包程序管理界面，联机输入：WebActivatorEx 搜索。

 

安装之后在App_Start文件夹下会自动生成的swagger配置文件SwaggerConfig.cs：

 

4、安装之后还没法正常访问swagger，需要配置网站属性：

 

修改自动生成的SwaggerConfig文件

注意配置生成的xml文档位置（swagger接口注释用的）：

c.IncludeXmlComments(string.Format("{0}/Doc/CYP.GMS.CooperativeBusiness.WebService.XML", System.AppDomain.CurrentDomain.BaseDirectory));
c.IncludeXmlComments(string.Format("{0}/Doc/CYP.GMS.CooperativeBusiness.Model.XML", System.AppDomain.CurrentDomain.BaseDirectory));

也可以自定义一个独立方法来配置：

c.IncludeXmlComments(GetXmlCommentsPath);

protected static string GetXmlCommentsPath()

{
        var xmlPath = System.String.Format(@"{0}/Doc/CYP.GMS.CooperativeBusiness.WebService.XML", System.AppDomain.CurrentDomain.BaseDirectory);
        return xmlPath ;
 }

注：这里的XML路径和文件名称必须与网站生成的XMl名称一致。

并且需要再WebApiConfig.cs配置中添加  config.Formatters.XmlFormatter.SupportedMediaTypes.Clear();

 

 

5、大功告成：在浏览器中输入如下地址：http://localhost:17420/swagger，显示如下页面：

点击相应的服务，在显示的框中输入对应的信息，再点击“Try it out！”，即可成功调用服务，并可查看返回的结果。

Swagger的一些高级用法

Swagger非常强大，不仅仅是一些帮助页面信息，还可以进行api的调试。这样就可以不用借助第三方工具 如：postman，进行webapi的调试。swagger经过配置，还可以输入一些http头部信息，如权限认证信息等。下面就来讲解以下具体的配置。

首先我们需要新建一个类 HttpHeaderOperation，让该类继承IOperationFilter 接口，该接口需引入命名空间：Swashbuckle.AspNetCore.SwaggerGen，实现接口方法Apply 代码如下：

public class HttpHeaderOperation : IOperationFilter
    {
        public void Apply(Operation operation, OperationFilterContext context)
        {
            if (operation.Parameters == null)
            {
                operation.Parameters = new List<IParameter>();
            }

            var actionAttrs = context.ApiDescription.ActionAttributes();

            var isAuthorized= actionAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));

            if (isAuthorized == false) //提供action都没有权限特性标记，检查控制器有没有
            {
                var controllerAttrs= context.ApiDescription.ControllerAttributes();

                isAuthorized= controllerAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
            }

            var isAllowAnonymous = actionAttrs.Any(a => a.GetType() == typeof(AllowAnonymousAttribute));

            if (isAuthorized && isAllowAnonymous == false)
            {
                operation.Parameters.Add(new NonBodyParameter()
                {
                    Name = "Authorization",  //添加Authorization头部参数
                    In = "header",
                    Type = "string",
                    Required = false
                });
            }
        }
    }

然后在 Startup.cs 中的 ConfigureServices 方法，找到之前的AddSwaggerGen 代码段，在最后添加如下代码：

c.OperationFilter<HttpHeaderOperation>()
services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "TwBusManagement接口文档",
                    Description = "RESTful API for TwBusManagement",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "Alvin_Su", Email = "alvin_su@outlook.com", Url = "" }
                });

                //Set the comments path for the swagger json and ui.
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "twbusapi.xml");
                c.IncludeXmlComments(xmlPath);

                c.OperationFilter<HttpHeaderOperation>(); // 添加httpHeader参数
            });

这样，我们允许webapi项目后，就可以输入 Authorization 头部参数了。如下图：