.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 头部参数了。如下图：