关于 Swashbuckle.AspNetCore3.0
一个使用 ASP.NET Core 构建的 API 的 Swagger 工具。直接从您的路线，控制器和模型生成漂亮的 API 文档，包括用于探索和测试操作的 UI。
项目主页：https://github.com/domaindrivendev/Swashbuckle.AspNetCore
项目官方示例：https://github.com/domaindrivendev/Swashbuckle.AspNetCore/tree/master/test/WebSites
之前写过一篇Swashbuckle.AspNetCore-v1.10 的使用,现在 Swashbuckle.AspNetCore 已经升级到 3.0 了，正好开新坑(博客重构)重新封装了下，将所有相关的一些东西抽取到单独的类库中,尽可能的避免和项目耦合，使其能够在其他项目也能够快速使用。
运行示例待博客重构完成再将完整代码开源，参考下面步骤可自行封装
我引用的版本如下
<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 项目中使用