之前也分享過 Swashbuckle.AspNetCore 的使用，不過版本比較老了，本次演示用的示例版本為 .net core 8.0，從安裝使用開始，到根據命名空間分組顯示，十分的有用 ...
前言
公司項目是是微服務項目，網關是手擼的一個.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 = "本地"
});
//配置模型標識，預設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())
}
};
})
修改完成後，可以結合自己業務來定義需要單獨顯示分組，最近又基於此加了一個開放平臺的介面，獨立於正常網關，單獨提供出去，一切都是剛剛好~
後語
如果有更好的方式，歡迎分享
若有錯誤，歡迎指出，謝謝
相關文檔
未經許可，禁止轉載!!!
作者：易墨
Github：yimogit
純靜態工具站點：metools
