从壹开始先后端分离【 .NET Core2.0/3.0 +Vue2.0 】框架之四 || Swagger的使用 3.2
本文3.0版本文章
https://mp.weixin.qq.com/s/SHNNQoYF-t8i2j85E1oSYAhtml
前言
若是想直接在域名的根目录直接加载 swagger 好比访问：localhost:8001 就能访问，能够这样设置：前端
app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1"); c.RoutePrefix = "";//路径配置，设置为空，表示直接访问该文件，
//路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件,注意localhost:8001/swagger是访问不到的，
//这个时候去launchSettings.json中把"launchUrl": "swagger/index.html"去掉， 而后直接访问localhost:8001/index.html便可
});
书接上文《从零开始搭建本身的先后端分离【 .NET Core2.0 Api + Vue 2.0 】框架之三 || Swagger的使用 3.1》，上文中只是简单的对如何使用Swagger做了介绍，并且最后也提出了几个问题，这里再重温下那几个问题：git
为什么直接 F5 运行，首页仍是没法加载？github
接口虽有，可是却没有相应的文字说明？json
项目开发中的实体类是如何在Swagger中展现的？后端
对于接口是如何加权限验证的？api
1、swagger的通常用法
0、设置swagger页面为首页——开发环境
在上一回中咱们提到，咱们直接F5运行项目，出现了系统默认页，服务器
虽然能够在输入/swagger后，顺利的访问swagger ui页，可是咱们发现每次运行项目，都会默认访问api/values这个接口，我想要将启动页设为swagger（或者是任意一个页面），你就须要用到了app
**设置文件launchSettings.json **了：框架
而后你再一次F5 运行，就会发现不同了，其余的配置，以及之后部署中的设置，咱们会在之后的文章中都有提到。
一、设置默认直接首页访问 —— 生产环境
上边的方法很正常，直接这么运行，就能够了，可是若是咱们部署到服务器，就会发现，上边的那种默认启动首页无效了，仍是须要咱们每次手动在域名后边输入 /swagger ，麻烦！
别慌，swagger 给咱们提供了这个扩展，咱们能够指定一个空字符，做为 swagger 的地址，在Configure中配置中间件：
app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint($"/swagger/v1/swagger.json", $"{ApiName} v1");//注意这个 v1 要和上边 ConfigureServices 中配置的大小写一致 // 将swagger设置成首页 c.RoutePrefix = ""; //路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件,注意localhost:8001/swagger是访问不到的，去launchSettings.json把launchUrl去掉 });
而后再把咱们上边的项目文件 launchSettings.json 的 launchUrl 给去掉就好了，这样咱们不管是本地开发环境，仍是生产环境，均可以默认首页加载了。
好比个人在线地址 ：http://123.206.33.109:8081
二、为接口添加注释
接下来，咱们就须要解决第二个问题，如何增长文字说明，就是传说中的注释：
右键项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个，固然老规矩，你也能够本身起一个名字：
这里我用的是相对路径，能够直接生成到 api 层的 bin文件夹下
这个时候，先别忙着运行项目，做为老司机的我，只要是改代码或者配置文件，保存后，第一件事就是看看有没有错误，一看，咦~~~果真，虽然是警告，能够强迫症呀，一看还挺多
别慌！一看，哦！原来是swagger把一些接口方法都经过xml文件配置了，就是刚刚上文提到的，因此咱们只须要加上方法注释就能够辣，能够左斜杠/，连续三下便可
若是你不想每个方法都这么加注释，能够这么配置（对当前项目进行配置，能够忽略警告，记得在后边加上分号 ;1591）：
如今呢，配置好了xml文件，接下来须要让系统启动的时候，去读取这个文件了，从新编辑Startup.cs，修改ConfigureServices函数：
public void ConfigureServices(IServiceCollection services) { services.AddMvc(); #region Swagger services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Version = "v0.1.0", Title = "Blog.Core API", Description = "框架说明文档", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = "https://www.jianshu.com/u/94102b59cc2a" } }); //就是这里 var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//这个就是刚刚配置的xml文件名 c.IncludeXmlComments(xmlPath,true);//默认的第二个参数是false，这个是controller的注释，记得修改 }); #endregion }
var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//这个就是刚刚配置的xml文件名 c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改
而后F5 运行，都加上了，感受前端大佬不再会说看不懂接口了，哈哈哈哈
三、对 Model 也添加注释说明
接下来开始第三个问题：添加实体类说明注释
新建一个.net core 类库Blog.Core.Model，注意是 .net core的类库，或者使用标准库也是能够的！（标准库能够在 NetCore 和 Framework 两个项目均可以跑）
/// <summary> /// 这是爱 /// </summary> public class Love { /// <summary> /// id /// </summary> public int Id { get; set; } /// <summary> /// 姓名 /// </summary> public string Name { get; set; } /// <summary> /// 年龄 /// </summary> public int Age { get; set; } }
这个时候，咱们只须要配置仿照上边 api 层配置的xml文档那样，在 Blog.Core.Model 层的 XML 输出到 API 层就好了：
二、API 层没有直接引用 Model 层，而是经过级联的形式；
就好比个人 Github 上的代码那样：
效果和上边是同样的，也算是引用 Model 层了。
四、改写注入方法，并在控制器中参数引用
配置xml文档
public void ConfigureServices(IServiceCollection services) { services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1); #region Swagger services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Version = "v0.1.0", Title = "Blog.Core API", Description = "框架说明文档", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = "https://www.jianshu.com/u/94102b59cc2a" } }); //就是这里 var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath; //就是这里 var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//这个就是刚刚配置的xml文件名 c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改 var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");//这个就是Model层的xml文件名 c.IncludeXmlComments(xmlModelPath); }); #endregion }
接口添加注释
/// <summary> /// post /// </summary> /// <param name="love">model实体类参数</param> [HttpPost] public void Post(Love love) { }
dang dang dang，就出来了
五、去掉Swagger警告提示
在Model层中，咱们创建了不少实体，若是你没有为每个实体都添加注释的话，可能会出现这样的警告：
若是有的小伙伴，不想添加注释，而又不想看到这个强迫症的警告提示，那就能够这么作，
右键项目 属性 -》 Errors and warnings 配置 1591：
六、隐藏某些接口
若是不想显示某些接口，直接在controller 上，或者action 上，增长特性
[ApiExplorerSettings(IgnoreApi = true)]
2、结语
对于接口是如何加权限验证的？
让咱们带着这些问题，继续浏览下一篇吧，Swagger 3.3 JWT 权限，必看篇。