1. AddSwaggerGen
AddSwaggerGen 是配置多个版本的swagger的关键
Path.Combine 当前项目运行的路径
UseSwaggerUI
主要分为 2 步骤 ：
1. 注册 Swagger
2. 使用 Swagger
为了不让program.cs 文件夹内容过于冗余 复杂 我们把步骤 1和 2 写成扩展的方法
program.cs 入口文件夹：
using Microsoft.OpenApi.Any; using Microsoft.OpenApi.Models; using WebApplication1.Utility.SwaggerExt; namespace WebApplication1 { public class Program { /// <summary> /// asdlfkasdio /// </summary> /// <param name="args"></param> public static void Main(string[] args) { var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); // 注册 Swagger CtmSwaggerExt.AddSwaggerExt(builder); var app = builder.Build(); // IsDevelopment 是否是开发环境 if (app.Environment.IsDevelopment()) { CtmSwaggerExt.UseSwaggerExt(app); } app.UseAuthorization(); app.MapControllers(); app.Run(); } } }
Utility 文件夹 用于存放扩展的方法 ；
ApiVersions.cs :
namespace WebApplication1.Utility.SwaggerExt { /// <summary> /// Swagger的版本控制 /// 使用枚举 /// </summary> public enum ApiVersions { front_dev, after_admin } }
CtmSwaggerExt.cs:
using Microsoft.OpenApi.Models; namespace WebApplication1.Utility.SwaggerExt { /// <summary> /// 自定义 Swagger扩展 /// 静态类中的静态方法 /// 扩展的方法都是使用静态类中的静态方法？？？ /// </summary> public static class CtmSwaggerExt { /// <summary> /// 注册 Swagger 的扩展方法 /// this 的作用是什么 /// builder 是 WebApplicationBuilder 的数据格式 /// </summary> /// <param name="builder"></param> public static void AddSwaggerExt(this WebApplicationBuilder builder) { var arr = typeof(ApiVersions).GetEnumNames().ToList(); builder.Services.AddEndpointsApiExplorer(); // swagger 配置 // 如果只要一个版本 builder.Services.AddSwaggerGen()即可 // 多个版本要用 option 配置 builder.Services.AddSwaggerGen(option => { // 通过版本枚举循环展示不同版本的swagger项目 Console.WriteLine("option开始配置多个swagger版本配置"); // 1. 枚举类型的数据格式转换List格式 arr.ForEach(version => { // ps 使用 OpenApiInfo 需要引入 using Microsoft.OpenApi.Models; option.SwaggerDoc(version, new OpenApiInfo() { // 标题 Title = $"{version}===标题", Version = $"{version}标注", Description = $"版本说明 {version}" }); }); // 2. 需要修改项目的属性 的生成 ==》 输出 ===》 文档文件 ==》 生成API文件 eg: WebApplication1.xml 文件 // 找到文档的绝对路径 xml 文件展示了控制器的注释内容[是要是文档注释都会显示的] var file = Path.Combine(AppContext.BaseDirectory, "WebApplication1.xml"); Console.WriteLine(file); // C:\Users\朱龙旭\Desktop\WebApplication1\WebApplication1\bin\Debug\net6.0\WebApplication1.xml // 显示控制器层注释 option.IncludeXmlComments(file, true); // 对action 的名称进行排序，如果有多个，就可以看见效果了 // option.OrderActionsBy(o => o.RelativePath); }); } /// <summary> /// 使用 Swagger 的扩展方法 /// app 是 WebApplication 数据类型 /// </summary> /// <param name="app"></param> public static void UseSwaggerExt(this WebApplication app) { var arr = typeof(ApiVersions).GetEnumNames().ToList(); app.UseSwagger(); app.UseSwaggerUI(option => { foreach (string version in arr) { // swagger.json 里面都是接口信息了 option.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{version}"); } }); } } }
控制器内容：
using Microsoft.AspNetCore.Mvc; using WebApplication1.Utility.SwaggerExt; namespace WebApplication1.Controllers { /// <summary> /// 测试注释是否展示 /// </summary> [ApiController] [Route("[controller]")] // 指定当前的控制器是哪个Swagger版本的 指定给 后台_version02 [ApiExplorerSettings(IgnoreApi = false,GroupName = nameof(ApiVersions.after_admin))] public class WeatherForecastController : ControllerBase { private static readonly string[] Summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }; private readonly ILogger<WeatherForecastController> _logger; /// <summary> /// DI /// </summary> /// <param name="logger"></param> public WeatherForecastController(ILogger<WeatherForecastController> logger) { _logger = logger; } /// <summary> /// GET方法 /// </summary> /// <returns></returns> [HttpGet(Name = "GetWea阿斯顿rFoasasst")] public IEnumerable<WeatherForecast> Get() { return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = Random.Shared.Next(-20, 55), Summary = Summaries[Random.Shared.Next(Summaries.Length)] }) .ToArray(); } /// <summary> /// POST方法 /// </summary> /// <returns></returns> [HttpPost] public IEnumerable<WeatherForecast> PostInfo() { // 随机生成 5 条对象数据 WeatherForecast 类型的 return Enumerable.Range(1, 5).Select(index => new WeatherForecast { test = "adsfasd", Date = DateTime.Now.AddDays(index), TemperatureC = Random.Shared.Next(-20, 55), Summary = Summaries[Random.Shared.Next(Summaries.Length)] }) .ToArray(); } /// <summary> /// PUT方法 /// </summary> /// <returns></returns> [HttpPut] public IEnumerable<WeatherForecast> PutInfo() { // 随机生成 5 条对象数据 WeatherForecast 类型的 return Enumerable.Range(1, 5).Select(index => new WeatherForecast { test = "adsfasd", Date = DateTime.Now.AddDays(index), TemperatureC = Random.Shared.Next(-20, 55), Summary = Summaries[Random.Shared.Next(Summaries.Length)] }) .ToArray(); } /// <summary> /// DELETE方法 /// </summary> /// <returns></returns> [HttpDelete] public IEnumerable<WeatherForecast> DeleteInfo() { // 随机生成 5 条对象数据 WeatherForecast 类型的 return Enumerable.Range(1, 5).Select(index => new WeatherForecast { test = "adsfasd", Date = DateTime.Now.AddDays(index), TemperatureC = Random.Shared.Next(-20, 55), Summary = Summaries[Random.Shared.Next(Summaries.Length)] }) .ToArray(); } } }