ASP .NET Core系列之Swagger配置（一）

官方文档：带有 Swagger/OpenAPI 的 ASP.NET Core Web API 文档 | Microsoft Learn

开发环境：VS2022+net6

(资料图)

目录

• 启用OpenAPI
• 版本控制
• 注释显示
• Token传递
• 文件上传按钮

启用OpenAPI支持（建议）

在新建项目时，建议勾选启用OpenAPI支持，勾选后会自动添加Swagger基本配置，直接看下一节即可

手动添加OpenAPI

1. 安装Nuget包Install-Package Swashbuckle.AspNetCore -Version 6.2.3
2. 改造Program.cs在var app = builder.Build();前添加：

builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen()

在var app = builder.Build();后添加：

app.UseSwagger();app.UseSwaggerUI();

版本控制

1. 新建版本说明类

public enum ApiVersions{/// 
/// 第一版/// 
V1,/// 
/// 第二版/// 
V2}

2. 改造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}");    });});

3. 在控制器或操作方法上标记版本

[ApiExplorerSettings(GroupName = nameof(ApiVersions.V1))]public class WeatherForecastController : ControllerBase

注释显示

显示效果

1. 生成XML注释文档

本质：生成一个WebApplication1.xml文件注意：如果参数的Model在其它类库，那么所引用的类库的.csproj文件也要加上上面的标识，并在Program.cs引入程序集的xml文件才能展示参数的注释

2. 改造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()        }    });    #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

实现方式：

1. 根据上面的规范，重新设置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 schema = new Dictionary();            schema["fileName"] = new OpenApiSchema { Description = "Select file", Type = "string", Format = "binary" };            Dictionary content = new Dictionary();            content["multipart/form-data"] = new OpenApiMediaType { Schema = new OpenApiSchema { Type = "object", Properties = schema } };            operation.RequestBody = new OpenApiRequestBody() { Content = content };        }    }}

2. 改造Program.cs

builder.Services.AddSwaggerGen(options =>{    #region 文件上传按钮    options.OperationFilter();    #endregion}

3. 控制器方法示例

[HttpPost]public JsonResult UploadFile(IFormCollection form){    return new JsonResult(new                          {                              Success = true,                              Message = "上传成功",                              FileName = form.Files.FirstOrDefault()?.FileName                          });}

关键词：