.net core 3.1 WebApi项目/Swagger支持二级目录

多个webapi项目需要进行集成部署，并且方便前端不产生跨域访问，那肯定是需要部署nginx进行转发，同一域名的情况下，只好采用二级目录进行区分，如果仅仅是webapi的接口转发，相对简单，配置nginx转向目标时添加/字符不转发二级目录路径即可。然而加上swagger后就不灵光了…

1、swagger的二级目录问题

.net core 3.1环境下，我们采用的是引入 Swashbuckle.AspNetCore包产生swagger的json文件，以及swagger ui。配置相对简单，估计百度上有很多了，这里也可以参考如下：
这里集成了jwt的授权头设定 。

public void ConfigureServices(IServiceCollection services)
{
           services.AddSwaggerGen(c =>
            {

                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = "后台API接口文档",
                    Description = "API",
                });
                //Set the comments path for the swagger json and ui.
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "XXX.Apis.xml");
                var dtolXmlPath = Path.Combine(basePath, "XXX.Service.xml");

                c.IncludeXmlComments(xmlPath);
                c.IncludeXmlComments(dtolXmlPath);                
                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[] { }
                    }
                });
                //c.EnableAnnotations();
            });
            // .net core 支持newstonsoftjson
            services.AddSwaggerGenNewtonsoftSupport();
}

在配置app内增加

 public void Configure(IApplicationBuilder app, IWebHostEnvironment env, ILoggerFactory factory)
{
app.UseSwagger();

            // Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint.
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "App API V1");
            });
}

如果采用忽略二级目录（不转发二级目录）的nginx配置方式，直接访问api是没有问题的，因为.net core app根本就没接收到二级目录。
直接访问swagger ui也是没问题的，然而在载入 swagger.json时由于是js载入的路径，会自动带上二级目录，这时候提示 【找不到\二级目录\swagger\v1\swagger.json】的错误提示，到此一步，我竟然轻易就放弃了。

以下是我的想法，未验证：
这时候应该可以直接修改swaggerui配置如下：

app.UseSwaggerUI(c =>
 {      
          c.SwaggerEndpoint($"/{VDir}/swagger/v1/swagger.json", "Vbms App API V1");
          c.RoutePrefix = $"{VDir}/swagger";     
  });

因为没有测试，不能说一定成功，有时间我测试下这个想法。

2、增加虚拟目录配置，并支持

首先nginx的配置仍然按照正常转发，二级目录直接转发到.net core app内，这时候对swagger进行如下配置，该配置是翻阅了asp.net core和swagger部分代码而知的，独家分享：

// 1.生成json文件时，生成到虚拟目录下，VDir 来自配置
app.UseSwagger(c =>
  {
       if (!string.IsNullOrEmpty(VDir))
       {
          // 设定模板：by webmote csdn
           c.RouteTemplate = $"/{VDir}/swagger/{{documentName}}/swagger.json";
           c.PreSerializeFilters.Add((swaggerDoc, httpReq) =>
           {
               //api测试时增加虚拟目录 或完整路径也可以，完整路径已被webmote注释
               swaggerDoc.Servers = new List<OpenApiServer> { new OpenApiServer {
               Url = $"/{VDir}"
              //  Url = $"{httpReq.Scheme}://{httpReq.Host.Value}/{virtualPath}"
           } };
           });
       }
   });

   // Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint.
   app.UseSwaggerUI(c =>
   {
       if (!string.IsNullOrEmpty(VDir))
       {
           c.SwaggerEndpoint($"/{VDir}/swagger/v1/swagger.json", "App API V1");
           c.RoutePrefix = $"{VDir}/swagger";
       }
       else
       {
           c.SwaggerEndpoint("/swagger/v1/swagger.json", "App API V1");
       }
   });

3、对Api增加虚拟目录支持

如果二级目录是固定的，你在控制期路由时，直接写死也是一个办法，只是不太灵活，哈哈。
例如： [Route("二级目录/api/[controller]/[action]")]
微软的某一篇文章说 使用 ~开头的路由路径可以支持虚拟目录，我试了，不行！

这里采用的时.net core 3引入的动态自定义路由方案,可以灵活配置。 增加自定义的路由转换类

public class MyTransformer : DynamicRouteValueTransformer
    {
        private string _route = string.Empty;
        public MyTransformer(string route)
        {
            _route = route;
        }
        public override ValueTask<RouteValueDictionary> TransformAsync(HttpContext httpContext, RouteValueDictionary values)
        {
            if (!values.ContainsKey("dir")) return new ValueTask<RouteValueDictionary>(values);

            var dir = (string)values["dir"];
            return new ValueTask<RouteValueDictionary>(values);
        }
    }

这里引入了{dir}路由配置，把该类注入到服务中

if (!string.IsNullOrEmpty(VDir))
 {
      services.AddSingleton<MyTransformer>(new MyTransformer(VDir));
  }

在终结点配置时，增加对二级目录的路由解释映射。

 app.UseEndpoints(endpoints =>
  {
       endpoints.MapControllers();
       if (!string.IsNullOrEmpty(VDir))
       {
           //这里是webmote定义的路由映射，可以方便的忽略二级目录
           endpoints.MapDynamicControllerRoute<MyTransformer>("{dir}/api/{controller}/{action}/{id?}");
       }
   });

控制器WebApi的路由保持不变，不需要增加二级目录的！
[Route("api/[controller]/[action]")]

4、结语

当遇到特别难处理的问题时，最好的办法时先搜索看看有无前辈解决过类似问题，如果没有的话，那就别迟疑了，快快翻看源代码，仔细查阅下有什么办法可以注入处理程序，拦截下原有处理方式。

1. 没事多阅读<微软文档>
2. 百度
3. csdn
4. 博客园
5. github 微软的asp.net core