ASP.NET Core WebAPI使用Swagger生成文档
介绍：
Swagger是为帮助我们生成webapi文档的工具
使用步骤：
添加Nuget：Swashbuckle.AspNetCore
添加服务：
public static class ServiceCollectionExtension
{
public static void AddSwagger(this IServiceCollection services)
{
//注册Swagger生成器
services.AddSwaggerGen(c =>
{
//定义一个或多个Swagger 文档
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/")
}，
Extensions = new Dictionary {
{ "powered by", new Microsoft.OpenApi.Any.OpenApiString(".net5 in kubernetes v1.17") }
}
});
// 为 Swagger JSON and UI设置xml文档注释路径
var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");
c.IncludeXmlComments(xmlPath);
// 开启支持在属性上添加注释，如：[SwaggerSchema("ID")]，内容会显示在UI中
c.EnableAnnotations();
});
}
}
添加中间件：
public static class IApplicationBuilderExtension
{
public static void UseSwaggerMiddleWare(this IApplicationBuilder app)
{
//生成SwaggerJSON终结点
//http://localhost:/swagger/{DocName}/swagger.json。如：/swagger/webapi/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
});
}
}
文档添加详细信息
修改终结点路径
UseSwagger():会生成终结点路由，通过/swagger/{DocName}/swagger.json可以访问
以下代码可修改默认的终结点路径,修改后的访问路径：（http://localhost:9005/api/swagger.json）（http://localhost:9005/webapi/swagger.json）
app.UseSwagger(options => { options.RouteTemplate = "/{documentName}/swagger.json"; options.SerializeAsV2 = true; });
文档排除指定接口
SwaggerUI中不显示指定接口，在需要排除的Controller或Action上添加特性：
[ApiExplorerSettings(IgnoreApi = true)]
为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 _logger;
public WeatherForecastController(ILogger logger)
{
_logger = logger;
}
///
/// 获取天气
///
///
/// 例子：
/// /WeatherForecast
///
/// 返回天气
[HttpGet]
public IEnumerable 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
{
///
/// 获取单个订单
///
///
/// 例子：
/// /order/1
///
///
/// 支持Newtonsoft：
使用Newtonsoft对接口参数序列化
添加Nuget包：
services.AddSwaggerGen(c =>
{
//省略....
}).AddSwaggerGenNewtonsoftSupport();//添加对Newtonsoft支持
SwaggerGenOptions参数类：
SwaggerDoc()：配置接口描述信息
OperationFilter()：可通过IOperationFilter接口去添加一些公共的参数
DocumentFilter通过IDocumentFilter接口去生成控制器的标签(描述)
参数类添加注释
添加Nuget包：
参数类添加注释：
public class OrderModel
{
[SwaggerSchema("订单主ID")]
public long ID { get; set; }
[SwaggerSchema("用户ID")]
public long UserID { get; set; }
}
ConfigureServices()方法中添加：
services.AddSwaggerGen(c =>
{
c.EnableAnnotations();
});
效果如下：
枚举属性显示属性名
效果如下：
services.AddSwaggerGen(c =>{
c.DescribeAllEnumsAsStrings();
}).AddSwaggerGenNewtonsoftSupport();
ReDoc UI
前面使用的是SWagger UI,还可以使用其他UI显示SWagger文档，比如：ReDoc UI
参考：
基础：
WebAPI分组：
KnifeUI: