.Core中使用Swagger并启用API文档的JWT授权

一、概述

刚参加工作时，写个API接口，还要写API文档，再使用PostMan测试接口，写文档的时间比写接口还要折腾。后来接触Swagger，API文档的工作得到了很大的改善，不但可以自动构建交互式API说明文档，还能直接调试API接口。今天记录下Core项目下使用Swagger，最新版的Swagger已经完美支持Open Api规范及JWT Token授权访问等。使用Swagger的好处总结如下：

• 使用 Swagger 生成精美的API接口文档
• 使用 Swagger 调试JWT授权接口
• 使用 Swagger 生成各个类库中视图模型的描述

二、使用Swagger

1、新建一个.NET Core 3.1 Web Api 项目，打开Nuget安装管理器，搜索Swashbuckle.AspNetCore，安装即可

 2、设置生成XML描述信息

右键--》属性-》生成

  3、开始配置Swagger

我们打开Startup.cs文件，来对Swagger配置进行一些必要的配置，在ConfigureServices方法我们添加一下Swagger配置：

　　　　public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = "TestSwaggerApi",
                    Description = "基于.NET Core 3.1 的测试实例",
                    Contact = new OpenApiContact
                    {
                        Name = "qxh",
                        Email = "2269667628@qq.com"
                    },
                });
                var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory;
                var xmlFile = System.AppDomain.CurrentDomain.FriendlyName + ".xml";
                var xmlPath = Path.Combine(baseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
            });
        }

然后我们在Configure方法里添加swagger中间件：

　　　　public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test");
                c.RoutePrefix = "swagger";
            });
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

这样swagger基本配置就完成了，看下效果

  

三、Swagger启用API文档的JWT授权

目前很多网站都使用了JWT（JSON WEB TOKEN）来作为账户系统的认证授权，JWT以它的简单、高效、分布式优势很快成为了网站的流行验证方式。接下来我们为Swagger添加JWT授权认证，依旧打开Startup.cs文件，修改上面ConfigureServices方法中的代码：

　　　　public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = "TestSwaggerApi",
                    Description = "基于.NET Core 3.1 的测试实例",
                    Contact = new OpenApiContact
                    {
                        Name = "qxh",
                        Email = "2269667628@qq.com"
                    },
                });
                c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
                {
                    Description = "在下框中输入请求头中需要添加Jwt授权Token：Bearer Token",
                    Name = "Authorization",
                    In = ParameterLocation.Header,
                    Type = SecuritySchemeType.ApiKey,
                    BearerFormat = "JWT",
                    Scheme = "Bearer"
                });

                c.AddSecurityRequirement(new OpenApiSecurityRequirement
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference {
                                Type = ReferenceType.SecurityScheme,
                                Id = "Bearer"
                            }
                        },
                        new string[] { }
                    }
                });
                var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory;
                var xmlFile = System.AppDomain.CurrentDomain.FriendlyName + ".xml";
                var xmlPath = Path.Combine(baseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
            });
        }

预览一下授权设置，发现右侧多了一个Authorize绿色的带锁按钮，这个按钮点开后就可以设置我们的JWT Token信息了，格式是：Bearer 你的Token字符串，注意Bearer于Token之间有个空格。设置好Token后，你请求任意的API接口时，Swagger会自动附带Token到请求的Header中。

 四、创建一个RESTFUL接口

上面我们已经实现了Swagger的各项配置，现在我们新建一个AccountController及一个通用视图模型，让Swagger返回带描述的接口文档。

1、新建AccountController

using Microsoft.AspNetCore.Mvc;

namespace SwaggerTest.Controllers
{
    /// <summary>
    /// 账户接口
    /// </summary>
    [Produces("application/json")]
    [Route("v1/[controller]")]
    [ApiController]
    public class AccountController : ControllerBase
    {
        /// <summary>
        /// 创建信息
        /// </summary>
        /// <param name="commonParamModel">参数</param>
        /// <returns>状态</returns>
        [HttpPost]
        public int Post([FromBody] CommonParamModel commonParamModel)
        {
            return 1;
        }

        /// <summary>
        /// 删除信息
        /// </summary>
        /// <param name="commonParamModel">参数</param>
        /// <returns></returns>
        [HttpDelete]
        public int Delete([FromQuery] CommonParamModel commonParamModel)
        {
            return 2;
        }

        /// <summary>
        /// 查询信息
        /// </summary>
        /// <param name="commonParamModel">参数</param>
        /// <returns></returns>
        [HttpGet]
        public int Get([FromQuery] CommonParamModel commonParamModel)
        {
            return 3;
        }

        /// <summary>
        /// 修改信息
        /// </summary>
        /// <param name="commonParamModel">参数</param>
        /// <returns></returns>
        [HttpPut]
        public int Put([FromQuery] CommonParamModel commonParamModel)
        {
            return 4;
        }
    }
}

2、创建公共视图模型

namespace SwaggerTest
{
    /// <summary>
    /// 公共参数model
    /// </summary>
    public class CommonParamModel
    {
        /// <summary>
        /// ID
        /// </summary>
        public long Id { get; set; }

        /// <summary>
        /// 账号
        /// </summary>
        public long Account { get; set; }

        /// <summary>
        /// 密码
        /// </summary>
        public long Password { get; set; }
    }
}

测试最终成果，随便展开一个API接口，可以看到我们给视图模型写的注释已经显示在Swagger上了，前端开发人员一看就懂，输入一些接口参数，点一下执行就能看到返回值了：

  

再看我们的请求Header中已经包含了JWT授权信息（Bearer abcdefghi）是我随意设置的，前端调试的时候换成需要的Token就行了。

 源码：https://github.com/qiuxianhu/CoreComponentDemo