Swashbuckle.AspNetCore3.0的二次封装与使用 (2)

添加对新建类库的引用，并在 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); } } 版本控制

添加 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，从了解到目前不支持多语言，其他的问题也可以查看此仓库
在使用过程中遇到的问题，基本上 readme 和 issues 都有答案，遇到问题多多阅读即可

参考文章

官方示例

Asp.Net Core 中使用 Swagger，你不得不踩的坑