ASP .NET Core从零到壹 || Swagger配置
Posted xcoast
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了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
);
08《JAVA从零到壹》第八讲：系统常用类（文末有课后作业）
❤️作者主页：小虚竹
❤️作者简介：大家好,我是小虚竹。Java领域优质创作者
以上是关于ASP .NET Core从零到壹 || Swagger配置的主要内容，如果未能解决你的问题，请参考以下文章
08《JAVA从零到壹》第八讲：系统常用类（文末有课后作业）