ASP.NETCore使用Swagger

什么是swagger

swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。

简单来讲，使用swagger能够自动生成友好的在线接口文档，并且支持接口测试，其好处：

• 对后端人员：减少了编写接口后还要花费时间同步更新接口文档，且与前端沟通的时间成本。
• 对前端人员：能够直观的快速的看到接口，并且进行在线测试，方便了调试调用接口，不用因接口问题频繁与后端沟通。

简单使用

步骤

框架.net3.1默认没有swagger，需要自己弄，以下简单写步骤

1. nuget安装

   Install-Package Swashbuckle.AspNetCore
   

2. Startup.cs文件引入命名空间

   using Swashbuckle.AspNetCore.Swagger;
   using Microsoft.OpenApi.Models;
   

3. 将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中

   //注册Swagger生成器，定义一个和多个Swagger 文档
   services.AddSwaggerGen(c =>
   {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
   });
   

4. 在 Startup.Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务

   //启用中间件服务生成Swagger作为JSON终结点
   app.UseSwagger();
   //启用中间件服务对swagger-ui，指定Swagger JSON终结点
   app.UseSwaggerUI(c =>
   {
       c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
   });
   

5. 此时启动项目就可通过http://localhost:<port>/swagger地址访问Swagger UI浏览API文档。

   也可通过http://localhost:<port>/swagger/v1/swagger.json地址访问生成的描述终结点的json文档。

6. 如果要想通过http://localhost:<port>/就访问Swagger UI，修改启用中间件SwaggerUI的方法UseSwaggerUI，把RoutePrefix 属性设置为空字符串。

   app.UseSwaggerUI(c =>
   {
       c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
       c.RoutePrefix = string.Empty;
   });
   

添加版本控制

步骤

1. 添加API枚举类型

   /// <summary>
   /// 版本控制
   /// </summary>
   public enum ApiVersion
   {
       /// <summary>
       /// v1版本
       /// </summary>
       V1 = 1,
       /// <summary>
       /// v2版本
       /// </summary>
       V2 = 2
         
   }
   

2. 修改Startup.ConfigureServices里注册Swagger的代码

   //注册Swagger生成器，定义一个和多个Swagger 文档
   services.AddSwaggerGen(c =>
   {
       //遍历版本信息
       typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
       {
           c.SwaggerDoc(version, new OpenApiInfo
           {
               Version = version, //版本号
               Title = $"My API {version}", //标题
               Description = $"My ASP.NET Core Web API {version}", //描述
               //上面三项最后设置，下面的三项可以不用
               TermsOfService = new Uri("https://example.com/terms"), //服务条款
               Contact = new OpenApiContact
               {
                   Name = "Singo", //联系人
                   Email = string.Empty,  //邮箱
                   Url = new Uri("https://github.com/hushitong"),//网站
               },
               License = new OpenApiLicense
               {
                   Name = "Use under LICX", //协议
                   Url = new Uri("https://example.com/license"), //协议地址
               }
           });
       });
   });
   

3. 修改Startup.Configure 里启用中间件的设置

   //启用中间件服务生成Swagger作为JSON终结点
   app.UseSwagger();
   //启用中间件服务对swagger-ui，指定Swagger JSON终结点
   app.UseSwaggerUI(c =>
   {
       c.RoutePrefix = string.Empty;
   
       typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
       {
           //描述终结点的json文档
           c.SwaggerEndpoint($"/swagger/{version}/swagger.json", version);
           //设置为none可折叠所有方法
           c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None);
       });
   });
   

4. 然后就是使用ApiExplorerSettingsAttribute标注各个版本Controller，然后修改路由信息

   原来的标注为

   [ApiExplorerSettings(GroupName = nameof(ApiVersion.V1))]
   

   后来的根据需要标注

   [ApiExplorerSettings(GroupName = nameof(ApiVersion.V2))]
   

5. 启动后就可以通过右上角的下拉框选择需要的版本进行测试了

注意

有关版本控制实际有很多办法，如：可以查看Net Core WebApi几种版本控制对比

添加JWT支持

1. 修改Startup.ConfigureServices里注册Swagger的代码

   //注册Swagger生成器，定义一个和多个Swagger 文档
   services.AddSwaggerGen(c =>
   {
       c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
   
       #region 添加JWT支持
       c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
       {
           Description = "在下框中输入请求头中需要添加Jwt授权Token：Bearer Token",
           Name = "Authorization", //设置其key名，请求时会添加上，默认使用Authorization名
           In = ParameterLocation.Header, //在请求头添加JWT Token
           Type = SecuritySchemeType.ApiKey,
           BearerFormat = "JWT",
           Scheme = "Bearer"
       });
   
       c.AddSecurityRequirement(new OpenApiSecurityRequirement
       {
           {
               new OpenApiSecurityScheme
               {
                   Reference = new OpenApiReference {
                       Type = ReferenceType.SecurityScheme,
                       Id = "Bearer"
                   }
               },
               new string[] { }
           }
       });
       #endregion
   });
   

2. 运行进入SeaggerUI页面，可以看到在页面右上角多了一个Authorize按钮，点击在value框可以填入bear <your jwt string>，以后请求头都会带上Authorization: bear <your jwt string>