ASP .NET Core从零到壹 || Swagger配置（一）
ASP .NET Core系列之Swagger配置（一）
官方文档：带有 Swagger/OpenAPI 的 ASP.NET Core Web API 文档 | Microsoft Learn
开发环境：VS2022+net6
目录
- 启用OpenAPI
- 版本控制
- 注释显示
- Token传递
- 文件上传按钮
启用OpenAPI支持（建议）
在新建项目时，建议勾选启用OpenAPI支持，勾选后会自动添加Swagger基本配置，直接看下一节即可
手动添加OpenAPI
- 安装Nuget包
Install-Package Swashbuckle.AspNetCore -Version 6.2.3 - 改造Program.cs
在var app = builder.Build();前添加：
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen()
在var app = builder.Build();后添加：
app.UseSwagger();
app.UseSwaggerUI();
版本控制
- 新建版本说明类
public enum ApiVersions
{
/// <summary>
/// 第一版
/// </summary>
V1,
/// <summary>
/// 第二版
/// </summary>
V2
}
- 改造Program.cs
builder.Services.AddSwaggerGen(options =>
{
#region 分版本的Swagger配置
//要启用swagger版本控制要在api控制器或者方法上添加特性[ApiExplorerSettings(GroupName = "版本号")]，这里是枚举
typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
{
options.SwaggerDoc(version, new Microsoft.OpenApi.Models.OpenApiInfo()
{
Title = $"当前版本{version}",
Version = version,
Description = $"这是第{version}版本"
});
});
#endregion
});
app.UseSwaggerUI(opotions =>
{
typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
{
opotions.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"版本：{version}");
});
});
- 在控制器或操作方法上标记版本
[ApiExplorerSettings(GroupName = nameof(ApiVersions.V1))]
public class WeatherForecastController : ControllerBase
注释显示
显示效果
- 生成XML注释文档
本质：生成一个WebApplication1.xml文件
注意：如果参数的Model在其它类库，那么所引用的类库的.csproj文件也要加上上面的标识，并在Program.cs引入程序集的xml文件才能展示参数的注释
- 改造Program.cs文件
builder.Services.AddSwaggerGen(options =>
{
#region 显示注释
// xml文档绝对路径
var file = Path.Combine(AppContext.BaseDirectory, "WebApplication1.xml");
//true:显示控制器层注释
options.IncludeXmlComments(file, true);
//对action的名称进行排序，如果有多个，就可以看见效果了。
options.OrderActionsBy(o => o.RelativePath);
#endregion
});
Token传递
效果显示
改造Program.cs文件：
builder.Services.AddSwaggerGen(options =>
{
#region 传入Token
//添加安全定义
options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Description = "请输入token,格式为Bearer xxxxxxxx(注意中间必须有空格)",
Name = "Authorization",
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
BearerFormat = "JWT",
Scheme = "Bearer"
});
// 添加安全要求
options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new List<string>()
}
});
#endregion
});
文件上传
效果显示
默认来说，Swagger是没有选择文件这个按钮的，但是当有API是要接收文件时就不方便测试了，这里可以通过增加一个IOperationFilter，也就是重写操作某个特定API的的过滤器来实现。
net6自带的Swagger支持的是OpenAPI 3，需要根据OpenAPI 3的规范来实现。
OpenAPI 3规范：
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
fileName:
type: string
format: binary
实现方式：
- 根据上面的规范，重新设置requestBody，代码如下：
public class FileUploadFilter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
//判断上传文件的类型，只有上传的类型是IFormCollection的才进行重写。
if (context.ApiDescription.ActionDescriptor.Parameters.Any(w => w.ParameterType == typeof(IFormCollection)))
{
Dictionary<string, OpenApiSchema> schema = new Dictionary<string, OpenApiSchema>();
schema["fileName"] = new OpenApiSchema { Description = "Select file", Type = "string", Format = "binary" };
Dictionary<string, OpenApiMediaType> content = new Dictionary<string, OpenApiMediaType>();
content["multipart/form-data"] = new OpenApiMediaType { Schema = new OpenApiSchema { Type = "object", Properties = schema } };
operation.RequestBody = new OpenApiRequestBody() { Content = content };
}
}
}
- 改造Program.cs
builder.Services.AddSwaggerGen(options =>
{
#region 文件上传按钮
options.OperationFilter<FileUploadFilter>();
#endregion
}
- 控制器方法示例
[HttpPost]
public JsonResult UploadFile(IFormCollection form)
{
return new JsonResult(new
{
Success = true,
Message = "上传成功",
FileName = form.Files.FirstOrDefault()?.FileName
});
}
