书接上回,上一章介绍了Swagger代替品Scalar,在使用中遇到不少问题,今天单独分享一下之前Swagger中常用的功能如何在Scalar中使用。
下面我们将围绕文档版本说明、接口分类、接口描述、参数描述、枚举类型、文件上传、JWT认证等方面详细讲解。
01、版本说明
我们先来看看默认添加后是什么样子的。
效果如下:
我们可以直接修改builder.Services.AddOpenApi()这行代码,修改这块描述,代码如下:
我们再来看看效果。
02、接口分类
通过上图可以看到菜单左侧排列着所有接口,现在我们可以通过Tags特性对接口进行分类,如下图我们把增删改查4个方法分为幂等接口和非幂等接口两类,如下图:
然后我们看看效果,如下图:
03、接口描述
之前使用Swagger我们都是通过生成的注释XML来生成相关接口描述,现在则是通过编码的方式设置元数据来生成相关描述。
可以通过EndpointSummary设置接口摘要,摘要不设置默认为接口url,通过EndpointDescription设置接口描述,代码如下:
运行效果如下:
04、参数描述
同样可以通过Description特性来设置参数的描述,并且此特性可以直接作用于接口中参数之前,同时也支持作用于属性上,可以看看下面示例代码。
效果如下图:
从上图可以发现除了描述还有默认值、必填项、可空等字样,这些是通过其他元数据设置的,对于属性还有以下元数据可以进行设置。
05、枚举类型
对于枚举类型,我们正常关注两个东西,其一为枚举项以int类型展示还是以字符串展示,其二为枚举项显示描述信息。
关于第一点比较简单只要对枚举类型使用JsonStringEnumConverter即可,代码如下:
效果如下:
通过上图也可以引发关于第二点的需求,如何对每个枚举项添加描述信息。
要达到这个目标需要做两件事,其一给每个枚举项通过Description添加元数据定义,其二我们要修改文档的数据结构Schema。
修改builder.Services.AddOpenApi(),通过AddSchemaTransformer方法修改文档数据结构,代码如下:
我们再来看看结果。
但是这也带来了一个问题,就是参数的默认值也是添加描述的格式,显然这样的数据格式作为参数肯定是错误的,因此我们需要自己注意,如下图。目前我也没有发现更好的方式即可以把每项枚举描述加上,又不影响参数默认值,有解决方案的希望可以不吝赐教。
06、文件上传
下面我们来看看文件上传怎么用,直接上代码:
然后我们测试一下效果。
首先我们可以看到请求示例中相关信息,这个相当于告诉我们后面要怎么选择文件上传,我们继续点击Test Request。
首先请求体需要选择multipart/form-data,上图请求示例中已经给出提示。
然后设置key为file,上图请求示例中已经给出提示,然后点击File上传图片,最后点击Send即可。
07、JWT认证
最后我们来看看如何使用JWT认证,
首先我们需要注入AddAuthentication及AddJwtBearer,具体代码如下:
然后我们需要继续修改builder.Services.AddOpenApi()这行代码,在里面加上如下代码:
其中BearerSecuritySchemeTransformer实现如下:
下面就可以通过[Authorize]开启接口认证,并实现一个登录接口获取token用来测试。
下面我们先用登录接口获取一个token。
我们先用token调用接口,可以发现返回401。
然后我们把上面获取的token放进去,请求成功。
在这个过程中有可能会遇到一种情况:Auth Type后面的下拉框不可选,如下图。
可能因以下原因导致,缺少[builder.Services.AddAuthentication().AddJwtBearer();]或[options.AddDocumentTransformer();]任意一行代码。
注:测试方法代码以及示例源码都已经上传至代码库,有兴趣的可以看看。https://gitee.com/hugogoos/Planner
热门跟贴