【从零开始搭建自己的.NET Core Api框架】（一）创建项目并集成swagger：1.2 swagger的高级应用
系列目录
三. 集成轻量级ORM框架——SqlSugar
前一章我们在项目中初步集成了swagger插件，但是还有一些问题需要解决，所以这一章要做的，就是完善swagger的相关设置。
1. 设置swagger ui页面为启动页
在前一章的末尾，我们通过在域名后面输入/swagger后，成功访问到swagger ui页，但是我们发现每次运行项目，都会默认访问api/values这个接口，我想要将启动页设为swagger（或者是你画好的任一个html页），那应该怎么设置呢？
位置就在Properties下的launchSettings.json文件里，只要将profiles下的launchUrl改成你需要的地址就可以
当然，文件里还有其他一些基本设置，比如端口设置，就不一一说了。
2. 注释问题
swagger很重要的一个功能，就是将我们接口的注释信息和参数（包括实体类）的注释信息显示到页面上。
现在我们分别将控制器、函数和参数添加相应的注释（添加方式是在类或函数的上一行敲三下“/”）
F5运行，发现swagger ui上并没有将它们显示出来。那是因为还缺少两步
2.1项目生成xml注释文件
右键项目名称=>属性=>生成
勾选“输出”下面的“生成xml文档文件”，后面填写保存该文档的地址（xml文件的名字可以修改，但是不建议修改保存的路径，然后记住这个地址，待会会用到）
操作完之后，我们会发现错误列表会多出很多黄色的警告，提示“缺少XML注释”。
这时只需要像之前那样，在类或函数的上面一行添加注释即可。（当然，如果没有强迫症的话，装作没看到也是不影响的~）
如果我们按照刚才记住的地址去文件夹查看，也能看到对应xml文件。
2.2启动类中添加swagger服务来读取这个xml文件
重新编辑Startup.cs，修改ConfigureServices函数：
/// <summary>
/// This method gets called by the runtime. Use this method to add services to the container.
/// </summary>
/// <param name="services"></param>
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
#region Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1.1.0",
Title = "Ray WebAPI",
Description = "框架集合",
TermsOfService = "None",
Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "RayWang", Email = "2271272653@qq.com", Url = "http://www.cnblogs.com/RayWang" }
});
//添加读取注释服务
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "APIHelp.xml");
c.IncludeXmlComments(xmlPath);
});
#endregion
}
以上两步完成之后，F5运行调试：
我们之前添加的注释就全部都出来了。
现在是不是突然觉得swagger很有用处了？
其实到这儿，细心的人都会发现，有一个地方还是没有显示注释，就是控制器的名称（在这个例子里就是values），我们之前在代码里明明也添加了注释，这里却没有显示出来，为什么？
好，接下来要放我个人私藏的大招了~
解决办法是：在项目中添加一个文件夹“SwaggerHelp”，在该文件加下添加类“SwaggerDocTag”，这个类的作用是根据控制器的名称向swagger ui额外附加注释，代码如下：
using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
namespace CKPI.SwaggerHelp
{
/// <summary>
/// Swagger注释帮助类
/// </summary>
public class SwaggerDocTag : IDocumentFilter
{
/// <summary>
/// 添加附加注释
/// </summary>
/// <param name="swaggerDoc"></param>
/// <param name="context"></param>
public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
swaggerDoc.Tags = new List<Tag>
{
//添加对应的控制器描述 这个是我好不容易在issues里面翻到的
new Tag { Name = "Values", Description = "测试模块" },
};
}
}
}
接下来要去Startup.cs添加相应的服务：
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using CKPI.SwaggerHelp;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using Microsoft.Extensions.PlatformAbstractions;
using Swashbuckle.AspNetCore.Swagger;
namespace RayPI
{
/// <summary>
///
/// </summary>
public class Startup
{
/// <summary>
///
/// </summary>
/// <param name="configuration"></param>
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
/// <summary>
///
/// </summary>
public IConfiguration Configuration { get; }
/// <summary>
/// This method gets called by the runtime. Use this method to add services to the container.
/// </summary>
/// <param name="services"></param>
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
#region Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1.1.0",
Title = "Ray WebAPI",
Description = "框架集合",
TermsOfService = "None",
Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "RayWang", Email = "2271272653@qq.com", Url = "http://www.cnblogs.com/RayWang" }
});
//添加注释服务
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "APIHelp.xml");
c.IncludeXmlComments(xmlPath);
//添加对控制器的标签(描述)
c.DocumentFilter<SwaggerDocTag>();
});
#endregion
}
/// <summary>
/// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
/// </summary>
/// <param name="app"></param>
/// <param name="env"></param>
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseMvc();
#region Swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
});
#endregion
}
}
}
现在再次运行调试，你会发现，控制器的注释就可以显示了
这儿的“测试模块”的注释，其实是从SwaggerDocTag类中读取出来的，并不是控制器本身的注释。
然后，这只是我个人目前为止发现的最好好用的方法，如果有人有什么其他更好的解决办法，欢迎大家指教，互相学习~
BTW，这里提一下可能会遇到的问题：如果项目发布之后，或是上线服务器之后，发现注释又没了，十有八九是生成的xml文件路径的问题。可以按照之前的步骤，依次排查，重新修改路径就可以了。
【20180705】更新显示控制器注释方法：
经@陆韦里同学私信指教，现提供另一种swagger展示控制器注释的方法，思路如下：
其实我们对控制器添加的注释，已经生成在xml注释文档里了（APIHelp.xml），打开xml文档，如下：
仔细观察下，其实就能找到它的规律：我们需要的主要数据都在二级节点<members>里，三级节点<member>有一个name属性，这个name的值凡是以“T:”开头的表示的都是类，凡是以“M:”开头的表示的都是函数，其中类里面凡是控制器必然会以“Controller”结尾。
所以我们要写一个读取xml的函数，根据这个规则，将注释提取出来，就可以了。
Stratup.cs里以前地配置不需要改变，只需要重新编辑SwaggerHelp下面的SwaggerDocTag.cs，添加一个GetControllerDesc函数，SwaggerDocTag.cs的完整代码如下：
using Microsoft.Extensions.PlatformAbstractions; using Swashbuckle.AspNetCore.Swagger; using Swashbuckle.AspNetCore.SwaggerGen; using System.Collections.Generic; using System.IO; using System.Xml; namespace RayPI.SwaggerHelp { /// <summary> /// Swagger注释帮助类 /// </summary> public class SwaggerDocTag : IDocumentFilter { /// <summary> /// 添加附加注释 /// </summary> /// <param name="swaggerDoc"></param> /// <param name="context"></param> public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context) { /* swaggerDoc.Tags = new List<Tag> { //添加对应的控制器描述 这个是我好不容易在issues里面翻到的 new Tag { Name = "Admin", Description = "后台" }, new Tag { Name = "Client", Description = "客户端" }, new Tag { Name = "System", Description = "系统" } }; */ swaggerDoc.Tags = GetControllerDesc(); } /// <summary> /// 从xml注释中读取控制器注释 /// </summary> /// <returns></returns> private List<Tag> GetControllerDesc() { List<Tag> tagList = new List<Tag>(); var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlpath = Path.Combine(basePath, "APIHelp.xml"); if (!File.Exists(xmlpath))//检查xml注释文件是否存在 return tagList; XmlDocument xmlDoc = new XmlDocument(); xmlDoc.Load(xmlpath); string memberName = string.Empty;//xml三级节点的name属性值 string controllerName = string.Empty;//控制器完整名称 string key = string.Empty;//控制器去Controller名称 string value = string.Empty;//控制器注释 foreach (XmlNode node in xmlDoc.SelectNodes("//member"))//循环三级节点member { memberName = node.Attributes["name"].Value; if (memberName.StartsWith("T:"))//T:开头的代表类 { string[] arrPath = memberName.Split('.'); controllerName = arrPath[arrPath.Length - 1]; if (controllerName.EndsWith("Controller"))//Controller结尾的代表控制器 { XmlNode summaryNode = node.SelectSingleNode("summary");//注释节点 key = controllerName.Remove(controllerName.Length - "Controller".Length, "Controller".Length); if (summaryNode != null && !string.IsNullOrEmpty(summaryNode.InnerText) && !tagList.Contains(new Tag { Name = key })) { value = summaryNode.InnerText.Trim(); tagList.Add(new Tag { Name = key, Description = value }); } } } } return tagList; } } }
点击F5运行，控制器的注释就显示出来了。
【20180705】再次更新显示控制器注释方法：
这次应该是终极解决办法了，而且这个方法其实swagger已经帮我们集成好了~
其中给swagger添加xml注释文件的函数叫“IncludeXmlComments”，F12跳转到定义，摘要是这样的：
// // 摘要: // Inject human-friendly descriptions for Operations, Parameters and Schemas based // on XML Comment files // // 参数: // filePath: // An abolsute path to the file that contains XML Comments // // includeControllerXmlComments: // Flag to indicate if controller XML comments (i.e. summary) should be used to // assign Tag descriptions. Don't set this flag if you're customizing the default // tag for operations via TagActionsBy. public void IncludeXmlComments(string filePath, bool includeControllerXmlComments = false);
可以看到，函数其实十有两个参数的，只是第二个参数默认设置了false，而这个参数就是设置是否显示显示控制器注释的。。。
所以只需要更改Startup.cs下ConfigureServices函数中的swagger配置就行了：
c.IncludeXmlComments(apiXmlPath, true);//添加控制器层注释（true表示显示控制器注释）
20180703更新：添加headers授权验证
3. 为Swagger添加头部授权验证功能
当接口添加了授权验证之后，我们是不能直接调用该接口，一般需要在发起的http请求的headers中添加“令牌"进行验证。用过Postman的应该知道，Postman是可以手动在headers中添加字段的，下面就要实现swagger添加headers的功能。
这里以JWT授权验证为例，如果需要了解JWT授权验证的，可以去该系列的第四篇【从零开始搭建自己的.NET Core Api框架】（四）实战！带你半个小时实现JWT授权验证，有专门介绍。
打开Startup.cs，我们需要在ConfigService函数中添加如下服务：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1.1.0",
Title = "Ray WebAPI",
Description = "框架集合",
TermsOfService = "None",
Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "RayWang", Email = "2271272653@qq.com", Url = "http://www.cnblogs.com/RayWang" }
});
//添加注释服务
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "APIHelp.xml");
c.IncludeXmlComments(xmlPath);
//添加对控制器的标签(描述)
c.DocumentFilter<SwaggerDocTag>();
//手动高亮
//添加header验证信息
//c.OperationFilter<SwaggerHeader>();
var security = new Dictionary<string, IEnumerable<string>> { { "Bearer", new string[] { } }, };
c.AddSecurityRequirement(security);//添加一个必须的全局安全信息，和AddSecurityDefinition方法指定的方案名称要一致，这里是Bearer。
c.AddSecurityDefinition("Bearer", new ApiKeyScheme
{
Description = "JWT授权(数据将在请求头中进行传输) 参数结构: \"Authorization: Bearer {token}\"",
Name = "Authorization",//jwt默认的参数名称
In = "header",//jwt默认存放Authorization信息的位置(请求头中)
Type = "apiKey"
});
});
完成之后，F5运行，swagger ui页面就会多出一个按钮"Authorize"，点击可以跳出token填写页面，作用可以去看第四章，这里就不讲了
【20180714】更新：设置swagger显示实体类信息（swagger读取多个xml注释文件）
4. 显示实体类注释
我们的WebApi接口大部分都是以实体类作为对象来传输的，但是swagger如果不设置的话是看不到这些实体类的注释的。
比如，实体类Student如下：
“添加学生”接口，需要接收一个“Student”类：
这里swagger只是把该实体类的字段一一列出来供测试填写数据，但是却看不到注释。
再比如，“获取单个学生”接口，调用 后会返回一个学生实体，但是Responses信息中却只显示了一个200的状态码，而没有显示该返回的实体类的信息：
下面，就来解决这个问题：
1）项目生成xml注释文件
这一步和之前一样，只是项目要选择实体类所在项目，而不是控制器层的项目：
这里注意点是，XML文档文件的路径最好选择到控制器层XML注释文件相同的路径下，如果生成成功，打开文件夹可以看到生成的xml文件：
2）设置swagger读取该xml注释文件
完整的ConfigureServices下swagger配置如下：
services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Version = "v1.1.0", Title = "Ray WebAPI", Description = "框架集合", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "RayWang", Email = "2271272653@qq.com", Url = "http://www.cnblogs.com/RayWang" } }); //添加注释服务 var basePath = PlatformServices.Default.Application.ApplicationBasePath; var apiXmlPath = Path.Combine(basePath, "APIHelp.xml"); var entityXmlPath = Path.Combine(basePath, "EntityHelp.xml"); c.IncludeXmlComments(apiXmlPath, true);//控制器层注释（true表示显示控制器注释） c.IncludeXmlComments(entityXmlPath); //添加控制器注释 //c.DocumentFilter<SwaggerDocTag>(); //添加header验证信息 //c.OperationFilter<SwaggerHeader>(); var security = new Dictionary<string, IEnumerable<string>> { { "Bearer", new string[] { } }, }; c.AddSecurityRequirement(security);//添加一个必须的全局安全信息，和AddSecurityDefinition方法指定的方案名称要一致，这里是Bearer。 c.AddSecurityDefinition("Bearer", new ApiKeyScheme { Description = "JWT授权(数据将在请求头中进行传输) 参数结构: \"Authorization: Bearer {token}\"", Name = "Authorization",//jwt默认的参数名称 In = "header",//jwt默认存放Authorization信息的位置(请求头中) Type = "apiKey" }); });
到这，第一个问题，接受实体类就可以显示注释了：
3）控制器的接口函数头设置标签
在接口的头部添加标签：
[ProducesResponseType(typeof(Student),200)]
表明该接口返回实体类类型。如下图例：
再次运行项目，查看获取单个学生接口：
点击黑框上面“Model”字样，还可以查看该类的注释~
另外，swagger还在接口的下方很贴心的生成了一个用于显示实体Model模块：
到这，我们的第一章的内容“搭建项目和集成sawgger”就结束了，如果有问题，欢迎留言一起讨论，互相学习。
本来想着代码比较简单，就不放源码，但是考虑之后，还是决定上传一下。正好也定个规矩，这个系列后面每完成一个大的章节之后，都上传一份源码。这样也是给自己一个交代吧。
源码下载：点击查看下载地址
下一章的内容是项目架构的搭建和集成SqlSugar
