如何在.net core项目中使用Swashbuckle.AspNetCore生成SwaggerUI

在公司的微服务项目中，网关是一个手撸的.net core webapi项目，使用refit封装了20多个服务SDK。网关负责统一调用和聚合处理，并提供给前端Swagger文档。然而，两年前文档还能够顺畅打开，但去年开始文档只能在本地打开，或者访问原始的Swagger页面。甚至有时候甚至连knife4j页面都打不开。因此，我决定对此进行优化。

安装Swashbuckle.AspNetCore包

首先记录一下安装及使用。之前我分享过Swashbuckle.AspNetCore的使用，不过版本比较老了。本次演示使用的示例版本为.net core 8.0。从安装使用开始分享一二。

安装包

• 新建.net core项目
• 添加Swashbuckle.AspNetCore相关包引用
• 设置项目xml生成路径，组件将根据xml解析接口相关信息

<ItemGroup>
  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
  <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.6.2" />
  <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="6.6.2" />
</ItemGroup>
<PropertyGroup>
  <DocumentationFile>bin\$(MSBuildProjectName).xml</DocumentationFile>
</PropertyGroup>

服务配置

• 一些基础配置使用备忘
• 配置文档信息
• 配置环境
• 配置模型标识
• 配置唯一标识
• 配置解析xml
• 启用数据注解

//框架初始化巴拉巴拉xxx
builder.Services.AddControllers();
//配置swagger
UseSwagger(builder.Services);

/// <summary>
/// Swagger 注入配置
/// </summary>
/// <param name="services"></param>
/// <returns></returns>
void UseSwagger(IServiceCollection services)
{
  //配置文档信息
  c.SwaggerDoc("v1", new OpenApiInfo
  {
    Title = "swagger接口文档测试",
    Description = "这是一个文档",
    Version = "v1",
  });
  //配置环境
  c.AddServer(new OpenApiServer()
  {
    Url = "",
    Description = "本地"
  });
  //配置模型标识，默认type.Name,名称一样，不同明明空间会报错，所以改成FullName,加上命名空间区分
  c.CustomSchemaIds(type => type.FullName);
  //配置唯一标识
  c.CustomOperationIds(apiDesc =>
  {
    var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
    return controllerAction.ControllerName + "-" + controllerAction.ActionName;
  });
  //解析站点下所有xml，一般加自己项目的引用的即可
  foreach (var file in Directory.GetFiles(AppContext.BaseDirectory, "*.xml"))
  {
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, file));
  }
  //启用数据注解
  c.EnableAnnotations(true, true);
}

• 启用swagger

RunSwagger(app);

/// <summary>
/// 启用swagger
/// </summary>
/// <param name="app"></param>
void RunSwagger(IApplicationBuilder app)
{
  app.UseSwaggerUI(c =>
  {
    c.SwaggerEndpoint("/v1/api-docs", "V1 Docs");
  });
  app.UseEndpoints(endpoints =>
  {
    endpoints.MapControllers();
    endpoints.MapSwagger("{documentName}/api-docs");
    endpoints.MapGet("/v3/api-docs/swagger-config", async (httpContext) =>
    {
      JsonSerializerOptions jsonSerializerOptions = new JsonSerializerOptions
      {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        IgnoreNullValues = true
      };
      jsonSerializerOptions.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, false));
      SwaggerUIOptions _options = new SwaggerUIOptions()
      {
        ConfigObject = new ConfigObject()
        {
          Urls = new List<UrlDescriptor>
          {
            new UrlDescriptor()
            {
              Url="/v1/api-docs",
              Name="V1 Docs"
            }
          }
        }
      };
      await httpContext.Response.WriteAsync(JsonSerializer.Serialize(_options.ConfigObject, jsonSerializerOptions));
    });
  });
}

运行

• 运行后可以看到配置成功，swagger文档已经生成

到这里基础的swagger配置已可以使用。更深层次的参考官方文档使用即可。接下来才是不一样的东西。随着我们的项目发展，当我们的服务越来越多，接口也越来越多的时候，swagger就从慢，到打开超时偶尔能打开，到每次都打不开(/api-docs过大返回超时，渲染卡顿)。这个时候，或者一开始就应该对swagger进行分组返回了，优化/api-docs接口返回的数据。当然，除了这种方式，还有可以加特效标记的方式，但是几百个服务，加不了一点。

分模块返回文档

一开始并没有想到分组显示，因为在本地运行的时候是可以打开的，只是json文件较大。于是做了一个优化是每次在发布应用后，请求一个接口去将swagger的json文件生成到本地，后续访问直接读取，算是暂时解决了打不开的问题。这样用了大半年，实在受不了这个速度。然后平时在看一些开源项目的时候发现是完全可以按自己的规则进行分组的，于是有了这篇文章。

为了兼容之前的文档路由，所以还是在原有配置的基础上，配置了其他模块的接口文档。可有两种方式。

• 一种是在原有基础上显示其他分组
• 一种是单独的swagger进行显示

优化修改

• 先定义好需要分组显示的模块

//设置需要分组的api接口
var groupApis = new List<string>() { "SwaggerTest.Controllers.Test", "SwaggerTest.Controllers.Demo" };

• UseSwagger修改部分
• 重点是这块的自定义，去分组中匹配路由c.DocInclusionPredicate官方文档

//配置文档信息
c.SwaggerDoc("v1", new OpenApiInfo
{
  Title = "swagger接口文档测试",
  Description = "这是一个文档",
  Version = "v1",
});
//配置环境
c.AddServer(new OpenApiServer()
{
  Url = "",
  Description = "本地"
});
//模型标识配置，默认type.Name,名称一样，不同明明空间会报错，所以改成FullName,加上命名空间区分
c.CustomSchemaIds(type => type.FullName);
c.CustomOperationIds(apiDesc =>
{
  var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
  return controllerAction.ControllerName + "-" + controllerAction.ActionName;
});
//加载注释文件
foreach (var file in Directory.GetFiles(AppContext.BaseDirectory, "*.xml"))
{
  c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, file));
}
//增加模块接口的注册
groupApis.ForEach(s =>
{
  c.SwaggerDoc(s, new OpenApiInfo
  {
    Title = "api-" + s,
    Description = "api " + s,
    Version = "v1",
  });
});

//启用数据注解
c.EnableAnnotations(true, true);
//自定义分组匹配
c.DocInclusionPredicate((docName, apiDes) =>
{
  if (groupApis.Contains(docName))
  {
    var displayName = apiDes.ActionDescriptor?.DisplayName?.ToLower() ?? string.Empty;
    var existGroup = groupApis.FirstOrDefault(s => displayName.Contains(s.ToLower()));
    return docName == existGroup;
  }

  return true;
});

• RunSwagger修改部分

app.UseSwaggerUI(c =>
{
  c.SwaggerEndpoint("/v1/api-docs", "V1 Docs");
  //默认页支持分组
  groupApis.ForEach(s =>
  {
    c.SwaggerEndpoint($"/{s}/api-docs", s);
  });
});
//单独的页面
groupApis.ForEach(s =>
{
  app.UseSwaggerUI(c =>
  {
    c.RoutePrefix = s;
    c.SwaggerEndpoint($"/{s}/api-docs", s);
  });
});
app.UseEndpoints(endpoints =>
{
  SwaggerUIOptions _options = new SwaggerUIOptions()
  {
    ConfigObject = new ConfigObject()
    {
      Urls = new List<UrlDescriptor>
      {
        new UrlDescriptor()
        {
          Url="/v1/api-docs",
          Name="V1 Docs"
        }
      }.Concat(groupApis.Select(s => new UrlDescriptor()
      {
        Url = $"/{s}/api-docs",
        Name = s
      }).ToList())
    }
  };
})

修改完成后，可以结合自己业务来定义需要单独显示分组。最近又基于此加了一个开放平台的接口，独立于正常网关，单独提供出去，一切都是刚刚好~

后语

如果有更好的方式，欢迎分享。若有错误，欢迎指出，谢谢。

相关文档

• Swashbuckle.AspNetCore
• 一篇比较细致的Swashbuckle使用教程