基于 .net core 8.0 的 swagger 文档优化分享-根据命名空间分组显示

前言

公司项目是是微服务项目，网关是手撸的一个.net core webapi 项目，使用 refit 封装了 20+ 服务 SDK，在网关中进行统一调用和聚合等处理，以及给前端提供 swagger 文档
在我两年前进公司的时候，文档还能够顺滑的打开，在去年的时候文档只能在本地打开，或者访问原始的 swagger 页面，knife4j 的页面更是打不开一点，于是想办法对此进行了优化

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

首先再记录一下安装及使用，之前也分享过 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>

服务配置

• 一些基础配置使用备忘
  • 配置文档信息 c.SwaggerDoc
  • 配置环境 c.AddServer
  • 配置模型标识 c.CustomSchemaIds
  • 配置唯一标识 c.CustomOperationIds
  • 配置解析 xml c.IncludeXmlComments
  • 启用数据注解 c.EnableAnnotations [SwaggerOperation]
• 完整配置如下

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

/// <summary>
/// Swagger 注入配置
/// </summary>
/// <param name="services"></param>
/// <returns></returns>
void UseSwagger(IServiceCollection services)
{
   
    services.AddSwaggerGen(c =>
    {
   
        //配置文档信息
        c.SwaggerDoc("v1", new OpenApiInfo
        {
   
            Title = "swagger接口文档测试",
            Description = "这是一个文档",
            Version = "v1",
        });
        //配置环境
        c.AddServer(new OpenApiServer()
        {
   
            Url = "",
            Description