001 C#配置多个版本Swagger说明

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();
        }
    }
}