Swashbuckle.AspNetCore3.0的二次封裝與使用
摘要：
關於 Swashbuckle.AspNetCore3.0
一個使用 ASP.NET Core 構建的 API 的 Swagger 工具。直接從您的路線，控制器和模型生成漂亮的 API 文件，包括用於探索和測試操作的 UI。
專案主頁： https://github.com/domai...
關於 Swashbuckle.AspNetCore3.0
一個使用 ASP.NET Core 構建的 API 的 Swagger 工具。直接從您的路線，控制器和模型生成漂亮的 API 文件，包括用於探索和測試操作的 UI。
專案主頁： ofollow,noindex" target="_blank">https://github.com/domaindrivendev/Swashbuckle.AspNetCore
專案官方示例： https://github.com/domaindrivendev/Swashbuckle.AspNetCore/tree/master/test/WebSites
之前寫過一篇 Swashbuckle.AspNetCore-v1.10 的使用 ,現在 Swashbuckle.AspNetCore 已經升級到 3.0 了，正好開新坑(部落格重構)重新封裝了下，將所有相關的一些東西抽取到單獨的類庫中,儘可能的避免和專案耦合，使其能夠在其他專案也能夠快速使用。
執行示例
封裝程式碼
待部落格重構完成再將完整程式碼開源，參考下面步驟可自行封裝
1. 新建類庫並新增引用
我引用的版本如下
<PackageReference Include="Microsoft.AspNetCore.Http.Abstractions" Version="2.1.1" /> <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.1" /> <PackageReference Include="Swashbuckle.AspNetCore" Version="3.0.0" />
2. 構建引數模型 CustsomSwaggerOptions.cs
public class CustsomSwaggerOptions
{
/// <summary>
/// 專案名稱
/// </summary>
public string ProjectName { get; set; } = "My API";
/// <summary>
/// 介面文件顯示版本
/// </summary>
public string[] ApiVersions { get; set; }
/// <summary>
/// 介面文件訪問路由字首
/// </summary>
public string RoutePrefix { get; set; } = "swagger";
/// <summary>
/// 使用自定義首頁
/// </summary>
public bool UseCustomIndex { get; set; }
/// <summary>
/// UseSwagger Hook
/// </summary>
public Action<SwaggerOptions> UseSwaggerAction { get; set; }
/// <summary>
/// UseSwaggerUI Hook
/// </summary>
public Action<SwaggerUIOptions> UseSwaggerUIAction { get; set; }
/// <summary>
/// AddSwaggerGen Hook
/// </summary>
public Action<SwaggerGenOptions> AddSwaggerGenAction { get; set; }
}
3. 版本控制預設引數介面實現 SwaggerDefaultValueFilter.cs
public class SwaggerDefaultValueFilter : IOperationFilter { public void Apply(Swashbuckle.AspNetCore.Swagger.Operation operation, OperationFilterContext context) { // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/412 // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/413 foreach (var parameter in operation.Parameters.OfType<NonBodyParameter>()) { var description = context.ApiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name); if (parameter.Description == null) { parameter.Description = description.ModelMetadata.Description; } if (parameter.Default == null) { parameter.Default = description.RouteInfo.DefaultValue; } parameter.Required |= !description.RouteInfo.IsOptional; } }
4. CustomSwaggerServiceCollectionExtensions.cs
public static class CustomSwaggerServiceCollectionExtensions
{
public static IServiceCollection AddCustomSwagger(this IServiceCollection services)
{
return AddCustomSwagger(services, new CustsomSwaggerOptions());
}
public static IServiceCollection AddCustomSwagger(this IServiceCollection services, CustsomSwaggerOptions options)
{
services.AddSwaggerGen(c =>
{
if (options.ApiVersions == null) return;
foreach (var version in options.ApiVersions)
{
c.SwaggerDoc(version, new Info { Title = options.ProjectName, Version = version });
}
c.OperationFilter<SwaggerDefaultValueFilter>();
options.AddSwaggerGenAction?.Invoke(c);
});
return services;
}
}
5. SwaggerBuilderExtensions.cs
public static class SwaggerBuilderExtensions
{
public static IApplicationBuilder UseCustomSwagger(this IApplicationBuilder app)
{
return UseCustomSwagger(app, new CustsomSwaggerOptions());
}
public static IApplicationBuilder UseCustomSwagger(this IApplicationBuilder app, CustsomSwaggerOptions options)
{
app.UseSwagger(opt =>
{
if (options.UseSwaggerAction == null) return;
options.UseSwaggerAction(opt);
});
app.UseSwaggerUI(c =>
{
if (options.ApiVersions == null) return;
c.RoutePrefix = options.RoutePrefix;
c.DocumentTitle = options.ProjectName;
if (options.UseCustomIndex)
{
c.UseCustomSwaggerIndex();
}
foreach (var item in options.ApiVersions)
{
c.SwaggerEndpoint($"/swagger/{item}/swagger.json", $"{item}");
}
options.UseSwaggerUIAction?.Invoke(c);
});
return app;
}
/// <summary>
/// 使用自定義首頁
/// </summary>
/// <returns></returns>
public static void UseCustomSwaggerIndex(this SwaggerUIOptions c)
{
var currentAssembly = typeof(CustsomSwaggerOptions).GetTypeInfo().Assembly;
c.IndexStream = () => currentAssembly.GetManifestResourceStream($"{currentAssembly.GetName().Name}.index.html");
}
}
6. 模型初始化
private CustsomSwaggerOptions CURRENT_SWAGGER_OPTIONS = new CustsomSwaggerOptions()
{
ProjectName = "墨玄涯部落格介面",
ApiVersions = new string[] { "v1", "v2" },//要顯示的版本
UseCustomIndex = true,
RoutePrefix = "swagger",
AddSwaggerGenAction = c =>
{
var filePath = System.IO.Path.Combine(System.AppContext.BaseDirectory, typeof(Program).GetTypeInfo().Assembly.GetName().Name + ".xml");
c.IncludeXmlComments(filePath, true);
},
UseSwaggerAction = c =>
{
},
UseSwaggerUIAction = c =>
{
}
};
7. 在 api 專案中使用
新增對新建類庫的引用，並在 webapi 專案中啟用版本管理需要為輸出專案新增 Nuget 包： Microsoft.AspNetCore.Mvc.Versioning ， Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer (如果需要版本管理則新增)
我引用的版本如下
<PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="2.3.0" /> <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer" Version="2.2.0" />
Startup.cs 程式碼
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
//版本控制
services.AddMvcCore().AddVersionedApiExplorer(o => o.GroupNameFormat = "'v'VVV");
services.AddApiVersioning(option =>
{
// allow a client to call you without specifying an api version
// since we haven't configured it otherwise, the assumed api version will be 1.0
option.AssumeDefaultVersionWhenUnspecified = true;
option.ReportApiVersions = false;
});
//custom swagger
services.AddCustomSwagger(CURRENT_SWAGGER_OPTIONS);
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
//custom swagger
//自動檢測存在的版本
// CURRENT_SWAGGER_OPTIONS.ApiVersions = provider.ApiVersionDescriptions.Select(s => s.GroupName).ToArray();
app.UseCustomSwagger(CURRENT_SWAGGER_OPTIONS);
app.UseMvc();
}
關鍵程式碼拆解
action 方法的 xml 註釋
new CustsomSwaggerOptions(){
AddSwaggerGenAction = c =>
{
var filePath = System.IO.Path.Combine(System.AppContext.BaseDirectory, typeof(Program).GetTypeInfo().Assembly.GetName().Name + ".xml");
//controller及action註釋
c.IncludeXmlComments(filePath, true);
}
}
當然還需要生成xml，編輯解決方案新增(或者在vs中專案屬性->生成->勾選生成xml文件檔案)如下配置片段
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'"> <DocumentationFile>.\專案名稱.xml</DocumentationFile> </PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>.\專案名稱.xml</DocumentationFile> </PropertyGroup>
目前.net core2.1我這會將此 xml 生成到專案目錄，故可能需要將其加入.gitignore中。
版本控制
新增 Nuget 包： Microsoft.AspNetCore.Mvc.Versioning ， Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
並在 ConfigureServices 中設定
//版本控制
services.AddMvcCore().AddVersionedApiExplorer(o => o.GroupNameFormat = "'v'VVV");
services.AddApiVersioning(option =>
{
// allow a client to call you without specifying an api version
// since we haven't configured it otherwise, the assumed api version will be 1.0
option.AssumeDefaultVersionWhenUnspecified = true;
option.ReportApiVersions = false;
});
controller 使用
/// <summary>
/// 測試介面
/// </summary>
[ApiVersion("1.0")]
[Route("api/v{api-version:apiVersion}/test")]
[ApiController]
public class TestController : ControllerBase
{
}
自定義主題
將 index.html 修改為內嵌資源就可以使用 GetManifestResourceStream 獲取檔案流,使用此 html，可以自己使用 var configObject = JSON.parse('%(ConfigObject)'); 獲取到 swagger 的配置資訊，從而根據此資訊去寫自己的主題即可。
/// <summary>
/// 使用自定義首頁
/// </summary>
/// <returns></returns>
public static void UseCustomSwaggerIndex(this SwaggerUIOptions c)
{
var currentAssembly = typeof(CustsomSwaggerOptions).GetTypeInfo().Assembly;
c.IndexStream = () => currentAssembly.GetManifestResourceStream($"{currentAssembly.GetName().Name}.index.html");
}
若想注入 css，js 則在 UseSwaggerUIAction 委託中呼叫對應的方法介面， 官方文件
另外，目前 swagger-ui 3.19.0 並不支援多語言，不過可以根據需要使用 js 去修改一些東西
比如在 index.html 的 onload 事件中這樣去修改頭部資訊
document.getElementsByTagName(
'span'
)[0].innerText = document
.getElementsByTagName('span')[0]
.innerText.replace('swagger', '專案介面文件')
document.getElementsByTagName(
'span'
)[1].innerText = document
.getElementsByTagName('span')[1]
.innerText.replace('Select a spec', '版本選擇')
在找漢化解決方案時追蹤到 Swashbuckle.AspNetCore3.0 主題時使用的 swagger-ui 為 3.19.0 ，從 issues2488 瞭解到目前不支援多語言，其他的問題也可以 檢視此倉庫
在使用過程中遇到的問題，基本上 readme 和 issues 都有答案，遇到問題多多閱讀即可