网站申请备案流程,嘉兴seo优化,wordpress主题 时间轴,做网站现在什么最赚钱吗目录
新建项目
RestFul
Swagger配置
注释展示
版本控制
Token传值
方法封装 新建项目
打开visual studio创建新项目#xff0c;这里我们选择.net core web api模板#xff0c;然后输入项目名称及其解决方案创建新项目 这里使用配置一些其他信息#xff0c;根据自己情…目录
新建项目
RestFul
Swagger配置
注释展示
版本控制
Token传值
方法封装 新建项目
打开visual studio创建新项目这里我们选择.net core web api模板然后输入项目名称及其解决方案创建新项目 这里使用配置一些其他信息根据自己情况进行选择 创建好项目之后我们可以看到 web api 模板运行的项目相比于MVC模式开发的项目初始文件是保留原有的控制器文件但是删除了模型和视图文件而且还加上了两个文件文件的作用相当于测试用例一一可以模拟发起请求如下所示 我们直接运行该项目可以看到我们打开了一个Swagger文件对于后端小白来说可能不太熟悉这个文件的作用但是对于前端开发者来讲可谓是非常熟悉的东西前端开发调用接口就需要经常和这个文件打交道如下所示 我们除了可以在Swagger上测试接口也可以在本地代码的测试用例处点击发起请求进行测试 这里做一个演示比如说我们想在Swagger文档中新增一组接口的话我们可以在控制器文件中设置一下get、post、delete、put请求操作如下我们将原本的文件复制一份然后命名为First然后设置一下接口类型如下所示 重新运行我们的项目然后打开Swagger可以看到我们创建的一组接口成功出现了这里接口的组名可以看到是 FirstController.cs 文件中Controller的前缀非常好识别 RestFul 背景近些年来随着移动互联网的发展前端设备层出不穷(手机、平板、桌面电脑、其他专用设备..)因此必须有一组统一的机制方便不同的前端设备与后端进行通信于是RestFul诞生了它可以通过一套统一的接口为WebiOS和Android等各种各样的终端提供服务。 特点RestFul把控制器作为维度当成一块资源对于这个资源会进行增删改查等各种当作这些动作必须都得有唯一的URL地址来匹配请求的Method的类型(get、post、put、delete)本质上就是用URL定位资源用HTTP(get、post、put、delete)描述操作。说白了就是一种软件架构设计风格而不是标准只是提供了一组设计原则和约束条件主要用于客户端和服务器交互类的软件基于这个风格设计的软件可以更简洁有层次更易于实现缓存等机制。
比如上文我们在控制器文件中设置了一组接口如果我们再在文件中添加比如说一个get接口请求运行项目其实是会报错的为什么就是因为这两个get请求的地址都是一样的编辑器没法识别到底哪个get请求是你想要的为了区分我们必须设置唯一的URL地址来避免报错如下 重新运行项目可以看到我们在First组当中又新增了一个新的get请求且两个get请求的URL路径是不一致的如下所示 对于路由约束的类型我们可以参考如下表格这些都可以作为接口传参的一个类型限定
限制示例匹配示例说明int{id: int}123456789, -123456789匹配任何整数bool{active: bool}true, false匹配true或false忽略大小写datetime{dob: datetime}2024-12-11,2024-12-12 7:32pm匹配满足datetime类型的值decimal{price: decimal}49.99, -1,000.01匹配满足decimal类型的值double{height: double}1234, -1001.01e8匹配满足double类型的值float{height: float}1234, -1001.01e8匹配满足float类型的值long{ticks: long}123456789, -123456789匹配满足long类型的值minlength(value){usename: minlength(4)}KOBE字符串长度不能小于4个字符maxlength(value){filename: maxlength(8)}CURRY字符串长度不能超过8个字符length(value){filename: length(12)}somefile.txt字符串长度必须是12个字符length(min,max){filename: length(8,16)}somefile.txt字符串长度必须介于8和16之间min(value){age: min(18)}20整数值必须大于18max(value){age: max(120)}119整数值必须小于120range(min, max){age: range(18, 120)}100整数值必须介于18和120之间alpha{name: alpha}Rick字符串必须由一或多a-z字母组成regex(expression){ssn:regex(^\d{3})}3字符串必须匹配指定的正则required
Swagger配置 虽然上面我设置了Swagger并成功运行了但是设想一个场景如果你是后端你写的代码你当然看的懂生成的Swagger接口也是知道是什么意思但是你把这个Swaager丢给前端前端是否看的懂呢如果看不懂是不是还要找后端沟通这样就增加了时间成本。所以后端不仅仅要不接口写对还要把Swagger文档写好这里我们就需要对其进行相应配置争取让其他人看懂自己写的接口这才是真正意义上一名后端应该做的事情如下所示
注释展示 注释是很重要的当我们写完一个接口之后我们就需要对这个接口的作用进行注释用来告诉前端后端给的这个接口作用和意义是什么如何设置Swagger注释展示呢请往下看 如下我们给接口代码写下注释注释的快捷键是///也就是三个斜杠即可生成然后右键项目点击属性勾选文档文件这个复选框 我们右键项目重新生成解决方案然后打开我们的项目资源管理目录可以看到在我们项目的obj目录下的最里层有生成了一个xml文件右键选择文本打开可以看到我们的注释就在里面 接下来如果说我们想把注释展示到Swagger文档中的话我们需要来到入口文件Program.cs对我们的Swagger进行一个配置给原本的AddSwaggerGen添加一个配置对象代码如下 builder.Services.AddSwaggerGen(option {#region 注释展示{// 获取应用程序所在目录绝对不受工作目录影响建议采用此方法获取路径string basePath AppContext.BaseDirectory;string xmlPath Path.Combine(basePath, netCoreWebApi.xml);option.IncludeXmlComments(xmlPath);}#endregion
});
回到Swagger文档中可以看到我们的注释已经成功的被渲染出来了方便前端的理解 版本控制 随着项目不断升级和开发的过程中我们还可能需要去对项目进行开发多个版本但是版本之间的Swagger是不同的不会放置在同一个Swagger文档下面我们打开Swagger文档也能看到右上角有个下拉框其就是支持不同的版本的切换的如何做请往下看 为了方便不同版本的切换这里我们直接在解决方案中新建项目设置一个独立的文件夹出来因为待会我们还要对其作一个扩展所以这里我们选择一个类库即可如下 生成的文件我们重命名为 ApiVersionInfo 然后设置静态成员V1到V5表明版本有5个如下所示 我们来到入口文件Program.cs文件处这里我们开始设置支持Swagger版本控制的代码这里我们借助 System.Reflection 中的FieldInfo反射机制中的类型来获取类型ApiVersionInfo中的所有字段信息然后通过OpenApiInfo来描述Swagger文档的元数据及包含了有关API的关键信息比如标题、版本、描述等如下所示 builder.Services.AddSwaggerGen(option {#region 注释展示{// 获取应用程序所在目录绝对不受工作目录影响建议采用此方法获取路径string basePath AppContext.BaseDirectory;string xmlPath Path.Combine(basePath, netCoreWebApi.xml);option.IncludeXmlComments(xmlPath);}#endregion#region 支持Swagger版本控制{foreach (FieldInfo filed in typeof(ApiVersionInfo).GetFields()){option.SwaggerDoc(filed.Name, new OpenApiInfo(){Title $netCoreWebApi API {filed.Name},Version filed.Name,Description $netCoreWebApi API {filed.Name} 版本});}}#endregion
});
接下来配置Swagger UI使得每个API版本都有一个对应的Swagger UI页面具体来说它会为每个API版本动态创建一个Swagger UI的入口从而允许用户查看不同版本的API文档如下 接下来我们来到编写接口代码的控制器文件给不同版本设置如下代码作用是将特定的API控制器或者方法标记为属于某个版本组从而使得Swagger等工具能够按版本组织和展示API文档 最终呈现的效果如下所示 Token传值 如果项目的接口需要授权才能被访问的话这里我们就需要通过token传值的方式来进行鉴权才能调试接口如何做呢请往下看 这里我们仍然在Swagger配置函数中设置token传值以及添加对应的安全要求如下所示 #region 支持token传值
{option.AddSecurityDefinition(Bearer, new OpenApiSecurityScheme(){Description JWT授权(数据将在请求头中进行传输) 参数结构: \Authorization: Bearer {token}\, // 描述Name Authorization, // 授权名称In ParameterLocation.Header, // 授权位置放在头信息进行传值Type SecuritySchemeType.ApiKey, // 授权类型BearerFormat JWT, // 格式是JWTScheme Bearer});// 添加安全要求option.AddSecurityRequirement(new OpenApiSecurityRequirement(){{new OpenApiSecurityScheme{Reference new OpenApiReference(){Id Bearer, // 必须和上面一致Type ReferenceType.SecurityScheme}},new string[] { }}});
}
#endregion
运行项目来到Swagger文档中可以看到我们已经成功添加了身份验证这里我们输入对应的JWT格式即可如下所示我们输入token之后发起请求如下已经带上了我们设置的token 方法封装
根据上面对Swagger的配置可以看到我们对Swagger的配置基本上都写在了入口Program.cs文件当中这样就显得非常的冗余入口文件代码量太多了这里我们可以将对Swagger的配置抽离到我们创建的类库当中新建一个文件夹用于专门存放Swagger配置的东西如下所示 这里设置一个函数然后把IServiceCollection设置为Service的类型该类型用于配置依赖注入容器的接口通常为Swagger配置服务我们直接把入口文件当中配置Swagger的代码直接粘贴过来
using System.Reflection;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;namespace netCoreWebApi.WebCore.SwaggerExt
{public static class SwaggerExtension{public static void AddSwaggerExtension(this IServiceCollection Service){Service.AddEndpointsApiExplorer();Service.AddSwaggerGen(option {#region 注释展示{// 获取应用程序所在目录绝对不受工作目录影响建议采用此方法获取路径string basePath AppContext.BaseDirectory;string xmlPath Path.Combine(basePath, netCoreWebApi.xml);option.IncludeXmlComments(xmlPath);}#endregion#region 支持Swagger版本控制{foreach (FieldInfo filed in typeof(ApiVersionInfo).GetFields()){option.SwaggerDoc(filed.Name, new OpenApiInfo(){Title $netCoreWebApi API {filed.Name},Version filed.Name,Description $netCoreWebApi API {filed.Name} 版本});}}#endregion#region 支持token传值{option.AddSecurityDefinition(Bearer, new OpenApiSecurityScheme(){Description JWT授权(数据将在请求头中进行传输) 参数结构: \Authorization: Bearer {token}\, // 描述Name Authorization, // 授权名称In ParameterLocation.Header, // 授权位置放在头信息进行传值Type SecuritySchemeType.ApiKey, // 授权类型BearerFormat JWT, // 格式是JWTScheme Bearer});// 添加安全要求option.AddSecurityRequirement(new OpenApiSecurityRequirement(){{new OpenApiSecurityScheme{Reference new OpenApiReference(){Id Bearer, // 必须和上面一致Type ReferenceType.SecurityScheme}},new string[] { }}});}#endregion});}public static void UseSwaggerExtension(this WebApplication app){app.UseSwagger();app.UseSwaggerUI(option {foreach (FieldInfo filed in typeof(ApiVersionInfo).GetFields()){option.SwaggerEndpoint($/swagger/{filed.Name}/swagger.json, filed.Name);}});}}
}
这里还需要在类库中安装一下主程序当中包这里注意意义名称和版本号 因为this修饰静态类中的静态方法上面创建的两个方法都是静态类中的静态方法同时第一个参数还用this进行修饰这种扩展方法可以把传参提到前面当成实例方法来进行调用接下来我们就在入口文件中调用这两个方法 最后我们重新运行项目如下可以看到我们的Swagger也可以被重新运行
