编辑于 2020/04/02
Jwt Bearer权限认证+Swagger 第二篇 已经完成了！
在. net core 3.1 WebApi中使用Swagger框架+Jwt权限验证 第二篇
前言
编辑API接口文档对任何一个开发人员来说都算是比较重复，又无聊的工作，所以，需要一种快速有效的方法来构建api说明文档并且具备一定的扩展能力。Swagger就具备这些能力，现在Swagger可以说是当下最受欢迎的生成REST APIs风格文档工具。
书写API文档的工具有很多，但是能称之为“框架”的，估计也只有swagger了。
一. 创建工程
创建 asp. net core WebAPI 3.1项目，这里就不过多演示了。
二. 安装Nuget包依赖
在Nuget包中搜索Swashbuckle.AspNetCore安装
博主当前安装的版本是5.2.1
Nuget包
三. 配置服务
Startup.cs 中 ConfigureServices方法
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
#region Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v0.1.0",
Title = "Blog.Core API",
Description = "API文档",
TermsOfService = new Uri("https://www.jianshu.com/u/1117a3ecacbc"),
Contact = new OpenApiContact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = new Uri("https://www.jianshu.com/u/1117a3ecacbc") }
});
});
#endregion
}
Startup.cs 中 Configure方法
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
#region Swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
//直接在根域名访问(localhost:8001/index.html)
//c.RoutePrefix = "";
});
#endregion
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
三. 运行
启动程序后，在Url后面添加Swagger即可访问Swagger
Url
这样，Swagger就搭建完成了，马上F5运行看看！是不是非常简单，运行结果如下。
Swagger
点击方法内的Try it out，再点击Execute，就完成了一次接口调用，是不是非常方便。
四. 接口方法显示注释
当接口非常多的时候，那么就需要在接口上显示中文注释，这样也方便前端在调用接口是方便理解。
1. 右键单击WebApi项目--属性--生成--输出
WebApi项目设置
2. 修改Startup.cs 中 ConfigureServices方法
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
#region Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v0.1.0",
Title = "Blog.Core API",
Description = "API文档",
TermsOfService = new Uri("https://www.jianshu.com/u/1117a3ecacbc"),
Contact = new OpenApiContact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = new Uri("https://www.jianshu.com/u/1117a3ecacbc") }
});
var basePath = AppContext.BaseDirectory;
var xmlPath = Path.Combine(basePath, "NetCore.Blogs.Swagger.xml");//这个就是刚刚配置的xml文件名
c.IncludeXmlComments(xmlPath, true);
});
#endregion
}
3. 在Controller的方法中进行注释
注释方法
当然也可以注释Controller
注释控制器
运行查看效果
显示效果
五. 忽略CS1591警告
编译后发现一大堆的CS1591警告，虽然不会造成程序的影响，但是强迫症患者看着难受。
忽略警告非常简单，只需要在
WebApi项目--属性--生成下
忽略警告设置
六. 设置swagger页面为首页
虽然可以通过输入/swagger进行访问swagger，但是这样还是不是很方便的。
1. 打开WebAPI项目下的launchsettings.json文件
Settings
2. 设置 launchUrl为swagger
launchUrl
再次启动，就会发现直接启定到Swagger页面了，是不是很方便。
