Swagger配置WebApi

﹏ヽ暗。殇╰゛Y 2023-01-15 08:11 186阅读 0赞

### 目录 ###

*  前言
 *  通用必备操作
 *   *  添加Swashbuckle.AspNetCore引用（.net 5项目创建完整版项目时会自动引用）
     *  创建版本枚举类
     *  添加中间件
 *  配置swagger版本管理
 *   *  一.创建版本枚举类
     *  二.在ConfigureServices中注册swagger
     *  三.添加中间件
     *  四.声明组名称及路由
     *  五.为公开方法声明访问修饰符及路由
 *  配置Token验证按钮
 *   *  一.在ConfigureServices中注册swagger
     *  二.添加中间件
 *  配置swagger显示注释
 *   *  一.添加xml
     *  二.在ConfigureServices中注册swagger
 *  配置jwt访问校验(需要了解jwt基础知识)
 *   *  一.添加Microsoft.AspNetCore.Authentication.JwtBearer引用
     *  二.在appsettings.json中配置jwt信息
     *  三.在ConfigureServices中注册swagger
     *  四.添加中间件
     *  五.为公开方法添加特性

# 前言 #

本篇介绍.net core ,.net 5 通用的swagger配置方式

GetHub源码地址： [点击跳转][Link 1].

# 通用必备操作 #

## 添加Swashbuckle.AspNetCore引用（.net 5项目创建完整版项目时会自动引用） ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3R4MTcyMTExMDI0MA_size_16_color_FFFFFF_t_70]

## 创建版本枚举类 ##

namespace SwaggerWebApi.Utilty
    { 
        public class CustomApiVersions
        { 
            public enum ApiVersions
            { 
                v1 = 1,
                v2 = 2,
                v3 = 3,
                v4 = 4
            }
        }
    }

## 添加中间件 ##

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
      { 
          if (env.IsDevelopment())
          { 
              app.UseDeveloperExceptionPage();
          }
          #region Swagger中间件
          app.UseSwagger();
    
          app.UseSwaggerUI(c =>
          { 
              typeof(ApiVersions).GetEnumNames().Reverse().ToList().ForEach(version =>
              { 
                  c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{version}");
              });
          });
    
          // app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerWebApi v1"));
          #endregion
    
          app.UseRouting();
    
          app.UseAuthorization();
    
          app.UseEndpoints(endpoints =>
          { 
              endpoints.MapControllers();
          });
      }

# 配置swagger版本管理 #

## 一.创建版本枚举类 ##

## 二.在ConfigureServices中注册swagger ##

services.AddSwaggerGen(c =>
      { 
          #region 动态注册swagger版本管理
          typeof(ApiVersions).GetEnumNames().Reverse().ToList().ForEach(version =>
          { 
              c.SwaggerDoc(version, new OpenApiInfo()
              { 
                  Title = $"{version}:版本标题",
                  Version = version,
                  Description = $"{version}版本的内部主要包含了XXXXX"
              });
          });
          #endregion
          //c.SwaggerDoc("v1", new OpenApiInfo { Title = "SwaggerWebApi", Version = "v1" });
      });

## 三.添加中间件 ##

## 四.声明组名称及路由 ##

GroupName = "v1"  "v1"名称需要与枚举类对应

[Route("api/[controller]")]
     [ApiExplorerSettings(GroupName = "v1")]
     [ApiController]
     public class V1Controller : Controller
     { 
     }

## 五.为公开方法声明访问修饰符及路由 ##

**名称相近的方法必须声明路由** 例如：AddNewV1与AddV1

[Route("api/[controller]")]
     [ApiExplorerSettings(GroupName = "v1")]
     [ApiController]
     public class V1Controller : Controller
     { 
    	[HttpGet]
        [Route("api/[controller]/GetV1")]
    	public string GetV1()
    	{ 
    	    return Newtonsoft.Json.JsonConvert.SerializeObject(new
    	    { 
    	        Title = "Hello World"
    	    });
    	}
     }

# 配置Token验证按钮 #

## 一.在ConfigureServices中注册swagger ##

#region Swagger
     //注册swagger服务
     services.AddSwaggerGen(c =>
     { 
         #region 添加Token验证按钮 
         //添加授权
         c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
         { 
             Description = "请输入Token，格式为：Bearer 带有开头的",
             Name = "Authorization",//jwt默认参数名称
             In = ParameterLocation.Header,//把jwt存放在header中
             Type = SecuritySchemeType.ApiKey,
             BearerFormat = "JWT",
             Scheme = "Bearer"
    
         });
         //认证方式，此方式为全局添加
         c.AddSecurityRequirement(new OpenApiSecurityRequirement
         { 
             { 
                 new OpenApiSecurityScheme{ 
                      Reference=new OpenApiReference{ 
                          Type=ReferenceType.SecurityScheme,
                          Id="Bearer"
                      }
                 },new string[] {  }
             }
         });
         #endregion
     });
     #endregion

## 二.添加中间件 ##

# 配置swagger显示注释 #

## 一.添加xml ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3R4MTcyMTExMDI0MA_size_16_color_FFFFFF_t_70 1]

## 二.在ConfigureServices中注册swagger ##

## 一.在ConfigureServices中注册swagger
    ```csharp
    #region Swagger
     //注册swagger服务
     services.AddSwaggerGen(c =>
     { 
         //添加中文注释
         var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
         Console.WriteLine("basePath: " + basePath);
         var commentsFileName = typeof(Program).Assembly.GetName().Name + ".XML";
         Console.WriteLine("commentsFileName: " + commentsFileName);
         var xmlPath = Path.Combine(basePath, commentsFileName);
         c.IncludeXmlComments(xmlPath);
     });
     #endregion

# 配置jwt访问校验(需要了解jwt基础知识) #

## 一.添加Microsoft.AspNetCore.Authentication.JwtBearer引用 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3R4MTcyMTExMDI0MA_size_16_color_FFFFFF_t_70 2]

## 二.在appsettings.json中配置jwt信息 ##

{ 
      "Logging": { 
        "LogLevel": { 
          "Default": "Information",
          "Microsoft": "Warning",
          "Microsoft.Hosting.Lifetime": "Information"
        }
      },
      "AllowedHosts": "*",
      "audience": "http://localhost:8082",
      "issuer": "http://localhost:8082",
      "SecurityKey": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDI2a2EJ7m872v0afyoSDJT2o1+SitIeJSWtLJU8/Wz2m7gStexajkeD+Lka6DSTy8gt9UwfgVQo6uKjVLG5Ex7PiGOODVqAEghBuS7JzIYU5RvI543nNDAPfnJsas96mSA7L/mD7RTE2drj6hf3oZjJpMPZUQI/B1Qjb5H3K3PNwIDAQAB"
    }

## 三.在ConfigureServices中注册swagger ##

#region jwt校验
    //使用方法详见https://blog.csdn.net/tx1721110240/article/details/110355328
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    { 
        options.TokenValidationParameters = new TokenValidationParameters
        { 
            ValidateIssuer = true,//是否验证Issuer
            ValidateAudience = true,//是否验证Audience
            ValidateLifetime = true,//是否验证失效时间
            ValidateIssuerSigningKey = true,//是否验证SecurityKey
            ValidAudience = this.Configuration["audience"],//Audience
            ValidIssuer = this.Configuration["issuer"],//Issuer，这两项和前面签发jwt的设置一致
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(this.Configuration["SecurityKey"])),//拿到SecurityKey
            //AudienceValidator = (m, n, z) =>
            //{ 
            // return m != null && m.FirstOrDefault().Equals(this.Configuration["audience"]);
            //},//自定义校验规则，可以新登录后将之前的无效
        };
    });
    #endregion

## 四.添加中间件 ##

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
      { 
          if (env.IsDevelopment())
          { 
              app.UseDeveloperExceptionPage();
          }
          #region Swagger中间件
          app.UseSwagger();
    
          app.UseSwaggerUI(c =>
          { 
              typeof(ApiVersions).GetEnumNames().Reverse().ToList().ForEach(version =>
              { 
                  c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{version}");
              });
          });
    
          // app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerWebApi v1"));
          #endregion
     	  #region jwt
          app.UseAuthentication();//注意添加这一句，启用验证
          #endregion
          app.UseRouting();
    
          app.UseAuthorization();
    
          app.UseEndpoints(endpoints =>
          { 
              endpoints.MapControllers();
          });
      }

## 五.为公开方法添加特性 ##

标识\[Microsoft.AspNetCore.Authorization.Authorize\] 表示 ：访问这个特性下的方法需要验证jwt  
标识\[Microsoft.AspNetCore.Authorization.AllowAnonymous\]表示 ：访问这个特性下的方法不需要验证jwt

**名称相近的方法必须声明路由** 例如：AddNewV1与AddV1

[Route("api/[controller]")]
     [ApiExplorerSettings(GroupName = "v1")]
     [ApiController]
     [Microsoft.AspNetCore.Authorization.Authorize]
     public class V1Controller : Controller
     { 
    	[HttpGet]
        [Route("api/[controller]/GetV1")]
        [Microsoft.AspNetCore.Authorization.AllowAnonymous]
    	public string GetV1()
    	{ 
    	    return Newtonsoft.Json.JsonConvert.SerializeObject(new
    	    { 
    	        Title = "Hello World"
    	    });
    	}
    	/// <summary>
        /// 这里是DeleteV1
        /// </summary>
        /// <returns>字符串</returns>
        [HttpDelete]
        [Route("api/[controller]/DeleteV1")]
        public string DeleteV1()
        { 
            return Newtonsoft.Json.JsonConvert.SerializeObject(new
            { 
                Success = true,
                Message = "操作成功"
            });
        }
     }

[Link 1]: https://github.com/tx1721110240/SwaggerWebApi
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3R4MTcyMTExMDI0MA_size_16_color_FFFFFF_t_70]: /images/20221022/d9ae4991922c492ead1dbed2b1bac700.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3R4MTcyMTExMDI0MA_size_16_color_FFFFFF_t_70 1]: /images/20221022/b49dbae23be74b899864e47ec2909283.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3R4MTcyMTExMDI0MA_size_16_color_FFFFFF_t_70 2]: /images/20221022/73ee5dea9b7e4bccbeac1e68acb6ce08.png