Asp.Net Core 配置 Swagger

1. Swagger 版本控制

1. 1 添加版本枚举类

public enum ApiVersion
    {
        V1,
        V2,
        V3
    }

1.2 在启动类中添加Swagger的配置

builder.Services.AddSwaggerGen(option =>
            {
                #region 分版本的Swagger配置
                typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
                {

                    option.SwaggerDoc(version, new OpenApiInfo()
                    {
                        Version = version,
                        Title = $"版本{version}",
                        Description = $"版本描述{version}"
                    });
                });
                #endregion
            });

app.UseSwaggerUI(option =>
            {
                typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
                {
                    option.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"版本：{version}");
                });
            });

1.3 在Controller上添加版本标签

[ApiExplorerSettings(IgnoreApi =false,GroupName = nameof(ApiVersion.V1))]

2. 让Swagger页面显示注释

2.1  在项目属性--生成--输出 中 勾选 文档文件，项目在生成对于的xml文件，路劲可以不配置，默认为生成的根目录

 2.2 在项目启动类中添加Swagger相关配置

builder.Services.AddSwaggerGen(option =>
            {
                #region 配置展示配置
                //xml的绝对路劲
                var file = Path.Combine(AppContext.BaseDirectory, "MyTodo.Api.xml");
                //true:现实控制器层注释
                option.IncludeXmlComments(file, true);
                //对Action的名称进行排序
                option.OrderActionsBy(o => o.RelativePath);

                #endregion    
            });

3. Swagger 添加安全验证

3.1 添加JWT验证相关Nuget包

3.2 在项目启动类中添加Swagger相关配置

builder.Services.AddSwaggerGen(option =>
            {
               #region 扩展传入Token

                //添加安全定义
                option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
                {
                    Description = $"请输入Token,格式为 Bearer xxxxxxxx (中间必须有空格)",
                    Name = "Authorization",
                    In = ParameterLocation.Header,
                    Type = SecuritySchemeType.ApiKey,
                    BearerFormat = "JWT",
                    Scheme = "Bearer"
                });

                //添加安全要求
                OpenApiSecurityRequirement keyValuePairs = new OpenApiSecurityRequirement();
                keyValuePairs.Add(new OpenApiSecurityScheme()
                {
                    Reference = new OpenApiReference()
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
                }, new string[] { });

                option.AddSecurityRequirement(keyValuePairs);

                #endregion

            });

4. 添加文件上传按钮

4.1 添加FileUploadFilter

    /// <summary>
    /// 扩展文件上传，展示文件上传按钮
    /// </summary>
    public class FileUploadFilter : IOperationFilter
    {
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            //只针对表单提交
            const string FileUploadContentType = "multipart/form-data";
            if (operation.RequestBody == null)
            {
                return;
            }
            if (!operation.RequestBody.Content.Any(x => x.Key.Equals(FileUploadContentType, StringComparison.InvariantCultureIgnoreCase)))
            {
                return;
            }
            //第一个参数类型为IFormCollection
            if (context.ApiDescription.ParameterDescriptions[0].Type == typeof(IFormCollection))
            {
                operation.RequestBody = new OpenApiRequestBody()
                {
                    Description = "文件上传",
                    Content = new Dictionary<string, OpenApiMediaType>() {
                        {
                            FileUploadContentType,
                            new OpenApiMediaType()
                            {
                                Schema = new OpenApiSchema()
                                {
                                    Type = "object",
                                    Required = new HashSet<string>(){ "file"},
                                    Properties = new Dictionary<string, OpenApiSchema>() {
                                        { "file",
                                            new OpenApiSchema()
                                            {
                                                Type = "string",
                                                Format = "binary"
                                            }
                                        }
                                    }
                                }
                            } 
                        }
                    }
                };
            }
        }
    }

4.2 在项目启动类中添加Swagger相关配置

builder.Services.AddSwaggerGen(option =>
            {
                #region 扩展文件上传按钮

                option.OperationFilter<FileUploadFilter>();

                #endregion
            });