【CSharp】在.NET6中使用Swagger
本文最后更新于 2024-05-08,文章可能存在过时内容,如有过时内容欢迎留言或者联系我进行反馈。
简介
Swagger 是一个开放源代码的框架,用于生成 API 文档和客户端代码,用于 RESTful API。在 .NET 6 中,Swagger 通常与 OpenAPI Specification 一起使用,后者是一个更现代的规范,用于描述 RESTful API
环境
.NET6
ASP.NET Core Web API
Visual Studio 2022
使用
创建Swagger
通过创建项目时进行创建
创建一个新项目,在搜索中输入
ASP.NET Core Web API
进行搜索,然后选中第一个,点击“下一步”。“项目名称”和“位置”根据自己项目实际进行修改,然后点击“下一步”。
框架选择
.NET6
,勾选上启用OpenAPI支持,然后点击“创建”。创建好项目后,直接启动项目,默认会进入到Swagger UI,就能看到Web API默认生成的一个天气预报的接口。
通过NuGet创建
在NuGet中搜索Swashbuckle.AspNetCore,并安装第一个。
在
Program.cs
文件中添加builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); f (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); }
扩展
版本控制
新建一个
enum
类,命名为ApiVersion
.cs。public enum ApiVersion { V1, V2, V3 }
新建一个工具类
SwaggerExtension.cs
。public static class SwaggerExtension { public static void AddSwaggerGenExt(this WebApplicationBuilder builder) { builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(options => { #region 版本控制 typeof(ApiVersion).GetEnumNames().ToList().ForEach(version => { options.SwaggerDoc(version, new OpenApiInfo() { Title = $"{version}:Api文档", Version = "v1", Description = $"https://blog.uptoz.cn" }); }); #endregion 版本控制 }); } }
接口注释
在项目属性中找到“生成”内的“输出”,然后将“文档文件”的“生成包含API文档的文件”给勾选上,最后保存并生成一下。
在前面新建的
SwaggerExtension
类中增加以下代码请将“project-name”替换成你项目实际名称。
public static class SwaggerExtension { public static void AddSwaggerGenExt(this WebApplicationBuilder builder) { builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(options => { #region 显示注释 { var file = Path.Combine(AppContext.BaseDirectory, "project-name.xml"); options.IncludeXmlComments(file, true); options.OrderActionsBy(o => o.RelativePath); } #endregion 显示注释 }); } /// <summary> Swagger中间件配置 </summary> /// <param name="app"> </param> public static void UseSwaggerExt(this WebApplication app) { app.UseSwagger(); app.UseSwaggerUI(options => { typeof(ApiVersion).GetEnumNames().ToList().ForEach(version => { options.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{version} API"); }); }); } }
Token验证
在前面新建的SwaggerExtension类中增加以下代码
public static class SwaggerExtension { public static void AddSwaggerGenExt(this WebApplicationBuilder builder) { builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(options => { #region Token校验 options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme { Description = "请输入Toke,格式为 Beare xxxxxxx", 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 string[] {} } }); #endregion Token校验 }); } }
- 感谢你赐予我前进的力量
赞赏者名单
因为你们的支持让我意识到写文章的价值🙏
评论
隐私政策
你无需删除空行,直接评论以获取最佳展示效果