.net core webapi swagger 配置

BBS.Extensions 项目 这里扩展了 中间件 和注入配置

项目文件 

添加 

<GenerateDocumentationFile>True</GenerateDocumentationFile>

 <NoWarn>$(NoWarn);1591</NoWarn>

生成xml文件

 

 

 

 

需要Nuget下载相关的包

Swashbuckle.AspNetCore.SwaggerUI

 

 

 

 

Swashbuckle.AspNetCore.Filters

用途是要在Swagger下可以输入 token

 

 

 注入扩展配置代码 需要显示 依赖的Model的xml注释

 

   /// <summary>
      /// Swagger注入扩展
      /// </summary>
      public static class SwaggerExtend
      {
          /// <summary>
          /// 扩展
         /// </summary>
         /// <param name="services"></param>
         /// <param name="BaseDirectoryPath"></param>
         public static void AddSwagger(this IServiceCollection services, string BaseDirectoryPath)
         {
             AddDefaultSwagger(services, options =>
             {
                 //开启小锁
                 options.OperationFilter<AddResponseHeadersFilter>();
                 options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
                 //在header 中添加token 传给后台
                options.OperationFilter<SecurityRequirementsOperationFilter>();

               //  options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
               //  {
               //      Description = "jwt授权直接在下框输入token,格式 bearer+空格+token",
               //      Name = "Authorization",//默认参数名称
               //      In = ParameterLocation.Header,
               //      Type = SecuritySchemeType.ApiKey
               //  });
　　                          

options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Description = "jwt授权直接在下框输入token,格式 bearer+空格+token",
Name = "Authorization",//默认参数名称
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
BearerFormat = "JWT",
Scheme = "Bearer"
});

//添加安全要求
options.AddSecurityRequirement(new OpenApiSecurityRequirement {
{
new OpenApiSecurityScheme{
Reference =new OpenApiReference{
Type = ReferenceType.SecurityScheme,
Id ="Bearer"
}
},new string[]{ }
}
});



 
                 options.SwaggerDoc("v1", new OpenApiInfo
                 {
                    Version = "v0,1,0",
                     Title = "BBS.API",
                     Description = "框架说明文档",
                     Contact = new OpenApiContact
                     {
                         Name = "BBS.Code",
                        Email = "8@qq.com",
                     }
                 });
                 DirectoryInfo directoryInfo = new DirectoryInfo(BaseDirectoryPath);
                 FileInfo[] fileInfos = directoryInfo.GetFiles("*.xml");
                 foreach (var fileInfo in fileInfos)
                 {
                     string xmlPath = Path.Combine(BaseDirectoryPath, fileInfo.FullName);
                     options.IncludeXmlComments(xmlPath, true);
                 }
            });
         }
         /// <summary>
         /// 默认
         /// </summary>
         /// <param name="services"></param>
         /// <param name="setupAction"></param>
         public static void AddDefaultSwagger(this IServiceCollection services, Action<SwaggerGenOptions> setupAction)
         {
            services.AddSwaggerGen(setupAction);
         }
    }

 

 

 

 

中间件的扩展

 这里注意route前缀为空 不用 swagger/Index.html 只需要 Index.html

 public static class SwaggerMiddleware
    {
        /// <summary>
        /// 扩展
        /// </summary>
        /// <param name="app"></param>
        /// <param name="version"></param>
        /// <returns></returns>
        public static IApplicationBuilder UseMySwagger(this IApplicationBuilder app, string version="v1")
        {
            UseDefaultSwagger(app,options =>
            {
                options.SwaggerEndpoint("/swagger/v1/swagger.json", version);
                //route前缀为空 不用 swagger/Index.html 只需要 Index.html
                options.RoutePrefix = "";
            });
            return app;
        }
        /// <summary>
        /// 默认
        /// </summary>
        /// <param name="app"></param>
        /// <param name="setupAction"></param>
        /// <returns></returns>
        public static IApplicationBuilder UseDefaultSwagger(this IApplicationBuilder app, Action<SwaggerUIOptions> setupAction)
        {
            app.UseSwagger();
            app.UseSwaggerUI(setupAction);
            return app;
        }
    }

如果配置了 RoutePrefix = "" 需要配置 launchSettings.json 

"launchUrl": " "

 

 

 使用配置好的注入扩展 和 中间件

 

 

 

 

 

 

 

 

测试验证

 

 

 

 

注意 swagger默认 访问http  如果 出现 postman访问 200 swagger 访问401 可能原因是 强制重定向 https了 需要将 app.UseHttpsRedirection() 注释掉

在.NET Core WebAPI中，使用 app.UseHttpsRedirection() 中间件可能导致部分请求（如Swagger的GET请求）因HTTPS重定向引发401未授权错误，而POST请求却能返回200。以下是具体原因及解决方案：

 

1. HTTPS重定向与认证逻辑冲突
   app.UseHttpsRedirection() 会将所有HTTP请求自动重定向到HTTPS端口。在此过程中，原始请求的 Authorization请求头可能丢失，导致后续认证中间件（如JWT验证）无法识别Token，从而返回401错误

   • GET请求特点：浏览器或Swagger UI默认优先使用HTTP访问，触发重定向时可能丢弃Header。
   • POST请求特点：若直接通过HTTPS访问（如Postman），或重定向逻辑未触发，则不会丢失Header。