.NET9 - Swagger平替Scalar详解（四）

server/2024/11/28 6:58:36/

书接上回，上一章介绍了Swagger代替品Scalar，在使用中遇到不少问题，今天单独分享一下之前Swagger中常用的功能如何在Scalar中使用。

下面我们将围绕文档版本说明、接口分类、接口描述、参数描述、枚举类型、文件上传、JWT认证等方面详细讲解。

在这里插入图片描述

01、版本说明

我们先来看看默认添加后是什么样子的。

public static void Main(string[] args)
{var builder = WebApplication.CreateBuilder(args);builder.Services.AddControllers();builder.Services.AddOpenApi();var app = builder.Build();app.MapScalarApiReference();app.MapOpenApi();app.UseAuthorization();app.MapControllers();app.Run();
}

效果如下：

在这里插入图片描述

我们可以直接修改builder.Services.AddOpenApi()这行代码，修改这块描述，代码如下：

builder.Services.AddOpenApi(options =>
{options.AddDocumentTransformer((document, context, cancellationToken) =>{document.Info = new(){Title = "订单微服务",Version = "v1",Description = "订单相关接口"};return Task.CompletedTask;});
});

我们再来看看效果。

在这里插入图片描述

02、接口分类

通过上图可以看到菜单左侧排列着所有接口，现在我们可以通过Tags特性对接口进行分类，如下图我们把增删改查4个方法分为幂等接口和非幂等接口两类，如下图：

在这里插入图片描述

然后我们看看效果，如下图：

在这里插入图片描述

03、接口描述

之前使用Swagger我们都是通过生成的注释XML来生成相关接口描述，现在则是通过编码的方式设置元数据来生成相关描述。

可以通过EndpointSummary设置接口摘要，摘要不设置默认为接口url，通过EndpointDescription设置接口描述，代码如下：

//获取
[HttpGet(Name = "")]
[Tags("幂等接口")]
[EndpointDescription("获取订单列表")]
public IEnumerable<Order> Get()
{return null;
}
//删除
[HttpDelete(Name = "{id}")]
[Tags("幂等接口")]
[EndpointSummary("删除订单")]
[EndpointDescription("根据订单id，删除相应订单")]
public bool Delete(string id)
{return true;
}

运行效果如下：

在这里插入图片描述

04、参数描述

同样可以通过Description特性来设置参数的描述，并且此特性可以直接作用于接口中参数之前，同时也支持作用于属性上，可以看看下面示例代码。

public class Order
{[property: Description("创建日期")]public DateOnly Date { get; set; }[property: Required][property: DefaultValue(120)][property: Description("订单价格")]public int Price { get; set; }[property: Description("订单折扣价格")]public int PriceF => (int)(Price * 0.5556);[property: Description("商品名称")]public string? Name { get; set; }
}
[HttpPut(Name = "{id}")]
[Tags("非幂等接口")]
public bool Put([Description("订单Id")] string id, Order order)
{return true;
}

效果如下图：

在这里插入图片描述

从上图可以发现除了描述还有默认值、必填项、可空等字样，这些是通过其他元数据设置的，对于属性还有以下元数据可以进行设置。

在这里插入图片描述

05、枚举类型

对于枚举类型，我们正常关注两个东西，其一为枚举项以int类型展示还是以字符串展示，其二为枚举项显示描述信息。

关于第一点比较简单只要对枚举类型使用JsonStringEnumConverter即可，代码如下：

[JsonConverter(typeof(JsonStringEnumConverter<OrderStatus>))]
public enum OrderStatus
{[Description("等待处理")]Pending = 1,[Description("处理中")]Processing = 2,[Description("已发货")]Shipped = 3,[Description("已送达")]Delivered = 4,
}

效果如下：

在这里插入图片描述

通过上图也可以引发关于第二点的需求，如何对每个枚举项添加描述信息。

要达到这个目标需要做两件事，其一给每个枚举项通过Description添加元数据定义，其二我们要修改文档的数据结构Schema。

修改builder.Services.AddOpenApi()，通过AddSchemaTransformer方法修改文档数据结构，代码如下：

options.AddSchemaTransformer((schema, context, cancellationToken) =>
{//找出枚举类型if (context.JsonTypeInfo.Type.BaseType == typeof(Enum)){var list = new List<IOpenApiAny>();//获取枚举项foreach (var enumValue in schema.Enum.OfType<OpenApiString>()){//把枚举项转为枚举类型if (Enum.TryParse(context.JsonTypeInfo.Type, enumValue.Value, out var result)){//通过枚举扩展方法获取枚举描述var description = ((Enum)result).ToDescription();//重新组织枚举值展示结构list.Add(new OpenApiString($"{enumValue.Value} - {description}"));}else{list.Add(enumValue);}}schema.Enum = list;}return Task.CompletedTask;
});

我们再来看看结果。

在这里插入图片描述

但是这也带来了一个问题，就是参数的默认值也是添加描述的格式，显然这样的数据格式作为参数肯定是错误的，因此我们需要自己注意，如下图。目前我也没有发现更好的方式即可以把每项枚举描述加上，又不影响参数默认值，有解决方案的希望可以不吝赐教。

在这里插入图片描述

06、文件上传

下面我们来看看文件上传怎么用，直接上代码：

[HttpPost("upload/image")]
[EndpointDescription("图片上传接口")]
[DisableRequestSizeLimit]
public bool UploadImgageAsync(IFormFile file)
{return true;
}

然后我们测试一下效果。

在这里插入图片描述

首先我们可以看到请求示例中相关信息，这个相当于告诉我们后面要怎么选择文件上传，我们继续点击Test Request。

首先请求体需要选择multipart/form-data，上图请求示例中已经给出提示。

在这里插入图片描述

然后设置key为file，上图请求示例中已经给出提示，然后点击File上传图片，最后点击Send即可。

在这里插入图片描述

07、JWT认证

最后我们来看看如何使用JWT认证，

首先我们需要注入AddAuthentication及AddJwtBearer，具体代码如下：

public class JwtSettingOption
{//这个字符数量有要求，不能随便写，否则会报错public static string Secret { get; set; } = "123456789qwertyuiopasdfghjklzxcb";public static string Issuer { get; set; } = "asdfghjkkl";public static string Audience { get; set; } = "zxcvbnm";public static int Expires { get; set; } = 120;public static string RefreshAudience { get; set; } = "zxcvbnm.2024.refresh";public static int RefreshExpires { get; set; } = 10080;
}
builder.Services.AddAuthentication(options =>
{options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
}).AddJwtBearer(options =>
{//取出私钥var secretByte = Encoding.UTF8.GetBytes(JwtSettingOption.Secret);options.TokenValidationParameters = new TokenValidationParameters(){//验证发布者ValidateIssuer = true,ValidIssuer = JwtSettingOption.Issuer,//验证接收者ValidateAudience = true,ValidAudiences = new List<string> { JwtSettingOption.Audience, JwtSettingOption.Audience },//验证是否过期ValidateLifetime = true,//验证私钥IssuerSigningKey = new SymmetricSecurityKey(secretByte),ClockSkew = TimeSpan.FromHours(1), //过期时间容错值，解决服务器端时间不同步问题（秒）RequireExpirationTime = true,};
});

然后我们需要继续修改builder.Services.AddOpenApi()这行代码，在里面加上如下代码：

在这里插入图片描述

其中BearerSecuritySchemeTransformer实现如下：

public sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken){var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();if (authenticationSchemes.Any(authScheme => authScheme.Name == JwtBearerDefaults.AuthenticationScheme)){var requirements = new Dictionary<string, OpenApiSecurityScheme>{[JwtBearerDefaults.AuthenticationScheme] = new OpenApiSecurityScheme{Type = SecuritySchemeType.Http,Scheme = JwtBearerDefaults.AuthenticationScheme.ToLower(),In = ParameterLocation.Header,BearerFormat = "Json Web Token"}};document.Components ??= new OpenApiComponents();document.Components.SecuritySchemes = requirements;foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations)){operation.Value.Security.Add(new OpenApiSecurityRequirement{[new OpenApiSecurityScheme{Reference = new OpenApiReference{Id = JwtBearerDefaults.AuthenticationScheme,Type = ReferenceType.SecurityScheme}}] = Array.Empty<string>()});}}}
}

下面就可以通过[Authorize]开启接口认证，并实现一个登录接口获取token用来测试。

[HttpPost("login")]
[EndpointDescription("登录成功后生成token")]
[AllowAnonymous]
public string  Login()
{//登录成功返回一个token// 1.定义需要使用到的Claimsvar claims = new[] { new Claim("UserId", "test") };// 2.从 appsettings.json 中读取SecretKeyvar secretKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(JwtSettingOption.Secret));// 3.选择加密算法var algorithm = SecurityAlgorithms.HmacSha256;// 4.生成Credentialsvar signingCredentials = new SigningCredentials(secretKey, algorithm);var now = DateTime.Now;var expires = now.AddMinutes(JwtSettingOption.Expires);// 5.根据以上，生成tokenvar jwtSecurityToken = new JwtSecurityToken(JwtSettingOption.Issuer,         //IssuerJwtSettingOption.Audience,       //Audienceclaims,                          //Claims,now,                             //notBeforeexpires,                         //expiressigningCredentials               //Credentials);// 6.将token变为stringvar token = new JwtSecurityTokenHandler().WriteToken(jwtSecurityToken);return token;
}

下面我们先用登录接口获取一个token。

在这里插入图片描述

我们先用token调用接口，可以发现返回401。

在这里插入图片描述

然后我们把上面获取的token放进去，请求成功。

在这里插入图片描述

在这个过程中有可能会遇到一种情况：Auth Type后面的下拉框不可选，如下图。

在这里插入图片描述

可能因以下原因导致，缺少[builder.Services.AddAuthentication().AddJwtBearer();]或[options.AddDocumentTransformer();]任意一行代码。

注：测试方法代码以及示例源码都已经上传至代码库，有兴趣的可以看看。https://gitee.com/hugogoos/Planner


http://www.ppmy.cn/server/145556.html

相关文章

Kubernetes 还是 SpringCloud？

Kubernetes 还是 SpringCloud？

前些年&#xff0c;随着微服务的概念提出以及落地&#xff0c;不断有很多的公司都加入到了这场技术革新中&#xff0c;现在可谓是人人都在做和说微服务。 提到微服务&#xff0c;Java栈内&#xff0c;就不得不提SpringBoot、SpringCloud、Dubbo。 近几年&#xff0c;随着Cloud …
阅读更多...
远离网上的广告和无用信息，自己动手搭建Tipask问答网站

远离网上的广告和无用信息，自己动手搭建Tipask问答网站

文章目录 前言1.Tipask网站搭建1.1 Tipask网站下载和安装1.2 Tipask网页测试1.3 cpolar的安装和注册 2. 本地网页发布2.1 Cpolar临时数据隧道2.2 Cpolar稳定隧道&#xff08;云端设置&#xff09;2.3 Cpolar稳定隧道&#xff08;本地设置&#xff09; 3. 公网访问测试4. 结语 前…
阅读更多...
C++——多态（下）

C++——多态（下）

目录 引言 多态 4.多态的原理 4.1 虚函数表指针 4.2 多态的原理 5.单继承和多继承关系的虚函数表 5.1 单继承中的虚函数表 5.2 多继承中的虚函数表 结束语 引言 接下来我们继续学习多态。 没有阅读多态&#xff08;上&#xff09;的可以点击下面的链接哦~ C——多态…
阅读更多...
RabbitMQ的预取值详解

RabbitMQ的预取值详解

RabbitMQ的预取值&#xff08;Prefetch Value&#xff09;是一个关键概念&#xff0c;它决定了消费者在从队列中获取消息时&#xff0c;一次性可以获取的消息数量。这一机制对于优化消息分发和消费者的负载均衡至关重要。 什么是RabbitMQ的预取值&#xff1f; 预取值是指消费者…
阅读更多...
前端项目的动态路由实现(vue)

前端项目的动态路由实现(vue)

一、引言 动态路由&#xff0c;很多场景是&#xff0c;有些页面必须是某些用户或者某些角色才能访问&#xff0c;所以呢&#xff0c;前端的代码即使不给页面的入口&#xff0c;但是要是直接在地址栏敲入相关地址页面还是可以被访问到。为了杜绝这种情况&#xff0c;就用到了动…
阅读更多...
表的操作DDL

表的操作DDL

创建表 character set 字符集 collate 校验规则 engine 存储引擎;属性要用 ‘,’ 隔开&#xff0c;最后一个属性不加 ‘,’ &#xff0c;不要忘了括号其中charset utf8 collate utf8_general_ci engine MyIsam;可以不写 create database usr_db; use usr_db; //创建表 user1 c…
阅读更多...
【vue3实现微信小程序】设置项目底部tab页面切换标签

【vue3实现微信小程序】设置项目底部tab页面切换标签

快速跳转&#xff1a; 我的个人博客主页&#x1f449;&#xff1a;Reuuse博客 新开专栏&#x1f449;&#xff1a;Vue3专栏 参考文献&#x1f449;&#xff1a;uniapp官网 免费图标&#x1f449;&#xff1a;阿里巴巴矢量图标库 ❀ 感谢支持&#xff01;☀ 前情提要 &#x…
阅读更多...
PG使用 INHERITS 创建的子表注意事项

PG使用 INHERITS 创建的子表注意事项

在 PostgreSQL 中&#xff0c;使用 INHERITS 创建的子表对主表的更改行为如下&#xff1a; 1. 新增字段 行为&#xff1a;子表会自动继承主表新增的字段。 示例&#xff1a; CREATE TABLE parent_table (id SERIAL PRIMARY KEY, name TEXT); CREATE TABLE child_table () INHE…
阅读更多...
最新文章

Copyright @ 2022~2023