ASP.NET Core WebAPI使用Swagger生成文档

介绍：

Swagger是为帮助我们生成webapi文档的工具

使用步骤：

添加Nuget：Swashbuckle.AspNetCore

添加服务：

    public static class ServiceCollectionExtension
    {
        public static void AddSwagger(this IServiceCollection services)
        {
            //注册Swagger生成器，定义一个和多个Swagger 文档
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo()
                {
                    Title = "v1 标题",
                    Version = "v1",
                    Description = "v1描述信息",
                    Contact = new Microsoft.OpenApi.Models.OpenApiContact
                    {
                        Name = "fan",
                        Email = "410577910@qq.com",
                        Url = new System.Uri("https://www.cnblogs.com/fanfan-90/")
                    },
                    License = new Microsoft.OpenApi.Models.OpenApiLicense
                    {
                        Name = "许可证名字",
                        Url = new System.Uri("https://www.cnblogs.com/fanfan-90/")
                    }
                });
                // 为 Swagger JSON and UI设置xml文档注释路径
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
                var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");
                c.IncludeXmlComments(xmlPath);
            });
        }
    }

添加中间件：

public static class IApplicationBuilderExtension
    {
        public static void UseSwaggerMiddleWare(this IApplicationBuilder app)
        {
            //启用中间件服务生成Swagger作为JSON终结点
            app.UseSwagger();
            //启用中间件服务对swagger-ui，指定Swagger JSON终结点
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1~~~");
                c.RoutePrefix = string.Empty;//SwaggerUI界面默认url是/swagger/index.html；修改后可通过 /index.html 访问SwaggerUI
            });
        }
    }

[ApiExplorerSettings]:为WebAPI分组

添加服务、中间件(v1、a1)

    public static class ServiceCollectionExtension
    {
        public static void AddSwagger(this IServiceCollection services)
        {
            //注册Swagger生成器，定义一个和多个Swagger 文档
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo()
                {
                    Title = "v1接口",
                    Version = "v1",
                    Description = "内部使用接口"
                });
                c.SwaggerDoc("a1", new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Title = "a1接口",
                    Version = "a1",
                    Description = "外部使用接口"
                });
                // 为 Swagger JSON and UI设置xml文档注释路径
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
                var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");
                c.IncludeXmlComments(xmlPath);
            });
        }
    }
    public static class IApplicationBuilderExtension
    {
        public static void UseSwaggerMiddleWare(this IApplicationBuilder app)
        {
            //启用中间件服务生成Swagger作为JSON终结点
            app.UseSwagger();
            //启用中间件服务对swagger-ui，指定Swagger JSON终结点
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1~~~");
                c.SwaggerEndpoint("/swagger/a1/swagger.json", "a1~~~");
                c.RoutePrefix = string.Empty;//SwaggerUI界面默认url是/swagger/index.html；修改后可通过 /index.html 访问SwaggerUI
            });
        }
    }

添加两个Controller，分别属于v1、a1：

    [ApiController]
    [ApiExplorerSettings(GroupName = "v1")]
    [Route("[controller]")]
    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;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }
        /// <summary>
        /// 获取天气
        /// </summary>
        /// <remarks>
        /// 例子：
        /// /WeatherForecast
        /// </remarks>
        /// <returns>返回天气</returns>
        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }

    [ApiController]
    [ApiExplorerSettings(GroupName = "a1")]
    [Route("[controller]")]
    public class OrderController : ControllerBase
    {
        /// <summary>
        /// 获取单个订单
        /// </summary>
        /// <remarks>
        /// 例子：
        /// /order/1
        /// </remarks>
        /// <param name="orderID"></param>
        /// <returns></returns>
        [HttpGet("/order/{order_id}")]
        public Order_master GetOne([FromRoute(Name = "order_id")]long orderID)
        {
            return new Order_master { ID = 1, Price = 10.1M };
        }
    }
    public class Order_master
    {
        public long ID { get; set; }
        public decimal Price { get; set; }
    }

参考：
基础：https://www.cnblogs.com/yilezhu/p/9241261.html
WebAPI分组：https://www.cnblogs.com/toiv/archive/2018/07/28/9379249.html
KnifeUI:https://www.cnblogs.com/igeekfan/p/IGeekFan-AspNetCore-Knife4jUI.html