net core webapi多版本控制与swagger(nswag)配置
前言
首先希望webapi 支持多版本,swagger针对不同的版本可进行交互。多版本控制基于Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 包,swagger可以选择Swashbuckle.AspNetCore和nswag.AspNetCore.由于我们系统使用的是nswag所以继续沿用,当然Swashbuckle.AspNetCore也和不错,有时间再总结。
版本控制
1.导入相关nuget。Swashbuckle.AspNetCore,nswag.AspNetCore.
2.添加api多版本控制服务
2.1.首先是让项目支持多版本的服务添加
services.AddApiVersioning(option =>
{
// 可选,为true时API返回支持的版本信息
option.ReportApiVersions = true;
// 不提供版本时,默认为1.0
option.AssumeDefaultVersionWhenUnspecified = true;
//版本信息放到header ,不写在不配置路由的情况下,版本信息放到response url 中
option.ApiVersionReader = new HeaderApiVersionReader("api-version");
// 请求中未指定版本时默认为1.0
option.DefaultApiVersion = new ApiVersion(1, 0);
}).AddVersionedApiExplorer(option =>
{ // 版本名的格式:v+版本号
option.GroupNameFormat = "'v'V";
option.AssumeDefaultVersionWhenUnspecified = true;
});
////获取webapi版本信息,用于swagger多版本支持
this.provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
服务我们已经注入了,下面我们看一下怎么webapi 多版本的支持
2.1.1.多版本的控制
1.QueryString
/// <summary>
/// 用户管理API
/// </summary>
[ServiceFilter(typeof(LogFilterAttribute))]
[ApiController]
[Route("api/[controller]/[action]")]
[ApiVersion("2.0")] public class UserController : ApiController
{}
当我们注册服务时不加 option.ApiVersionReader = new HeaderApiVersionReader("api-version"); 那么版本信息就是通过url?api-version=2进行传递
2.header
如果不指定版本路由那么定义ApiVersionReader 则通过header传递
以上两种方式,默认版本(v1.0)均可不传递版本号
3.版本路由
/// <summary>
/// 用户管理API
/// </summary>
[ServiceFilter(typeof(LogFilterAttribute))]
[ApiController]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
[Authorize]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class UserController : ApiController
{}
这种方式很直观,但如果原有项目没有使用多版本控制不建议用,可采用header的方式更为合理一些,
2.1.2 同一个 Controller 支持多版本
增加多个 [ApiVersion("2.0")]即可。
但是两个相同的版本中Controller不能有相同的方法。比如v1 文件夹和v2文件的UserController都指向v2版本,是不能同时拥有GetList()的,但是如果我们想要v2中的GetList重写v1的GetList方法,其他的方法都继承过来怎么处理呢?
v1 版本中的controller指定[ApiVersion("1.0")][ApiVersion("2.0")]
/// <summary>
/// v1.用户管理API
/// </summary>
[ServiceFilter(typeof(LogFilterAttribute))]
[ApiController]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
//[Authorize]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class UserController : ApiController
{}
v2版本中的controller指定[ApiVersion("2.0")]
/// <summary>
/// v1.用户管理API
/// </summary>
[ServiceFilter(typeof(LogFilterAttribute))]
[ApiController]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
//[Authorize]
[ApiVersion("2.0")]
public class UserController : ApiController
{}
v1版本中的GetList()方法 MapToApiVersion到v1即可
/// <summary>
/// 获取用户列表
/// </summary>
/// <returns></returns>
[HttpGet,MapToApiVersion("1.0")]
public NetResponse<List<User>> GetList()
{}
这样以来v1与v2中的GetList 就互不影响了。
3.注册nswag(AddOpenApiDocument和AddSwaggerDocument)
NSwag注入服务有两个方法:AddOpenApiDocument和AddSwaggerDocument,两者的区别就是架构类型不一样,AddOpenApiDocument的SchemaType使用的是OpenApi3,AddSwaggerDocument的SchemaType使用的是Swagger2:
我用的是AddSwaggerDocument
foreach (var description in provider.ApiVersionDescriptions)
{
services.AddSwaggerDocument(document =>
{
document.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT token"));
document.DocumentName = description.GroupName;
document.Version = description.GroupName;
document.ApiGroupNames = new string[] { description.GroupName };//如果相同版本信息路由下增加
[ApiExplorerSettings(GroupName = "v1")]进行区分即可
//jwt 认证
document.AddSecurity("JWT token", Enumerable.Empty<string>(),
new OpenApiSecurityScheme()
{
Type = OpenApiSecuritySchemeType.ApiKey,
Name = nameof(Authorization),
In = OpenApiSecurityApiKeyLocation.Header,
Description = "将token值复制到如下格式: \nBearer {token}"
}
); });
}
4.nswag中间件
app.UseOpenApi();
app.UseSwaggerUi3(setting =>
{
});
是的我们做任何配置,如果你愿意其实有很多好玩的。但上面的配置方式足够多版本的控制与nswag交互。
net core webapi多版本控制与swagger(nswag)配置的更多相关文章
- net core webapi多版本控制与nswag 交互
前言 首先希望webapi 支持多版本,swagger针对不同的版本可进行交互.netcore 基于Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 包, ...
- Asp.net core WebApi 使用Swagger生成帮助页
最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core webapi来进行开发,开始每次调试以及与前端人员的沟通上都存在这效 ...
- Asp.net core WebApi 使用Swagger生成帮助页实例
最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core webapi来进行开发,开始每次调试以及与前端人员的沟通上都存在这效 ...
- net core WebApi 使用Swagger
Asp.net core WebApi 使用Swagger生成帮助页 最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core ...
- .net core webapi 前后端开发分离后的配置和部署
背景:现在越来越多的企业都采用了在开发上前后端分离,前后端开发上的分离有很多种,那么今天,我来分享一下项目中得的前后端分离. B/S Saas 项目:(这个项目可以理解成个人中心,当然不止这么点功能 ...
- ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...
- ASP.NET Core WebApi使用Swagger生成api
引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...
- 【转】ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
原文链接:https://www.cnblogs.com/yilezhu/p/9241261.html 引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必 ...
- Asp.net Core WebApi 使用Swagger做帮助文档,并且自定义Swagger的UI
WebApi写好之后,在线帮助文档以及能够在线调试的工具是专业化的表现,而Swagger毫无疑问是做Docs的最佳工具,自动生成每个Controller的接口说明,自动将参数解析成json,并且能够在 ...
随机推荐
- RHSA-2017:2679-重要: 内核 安全更新(需要重启、存在EXP、代码执行)
[root@localhost ~]# cat /etc/redhat-release CentOS Linux release 7.2.1511 (Core) 修复命令: 使用root账号登陆She ...
- ConcurrentHashMap源码解析,多线程扩容
前面一篇已经介绍过了 HashMap 的源码: HashMap源码解析.jdk7和8之后的区别.相关问题分析 HashMap并不是线程安全的,他就一个普通的容器,没有做相关的同步处理,因此线程不安全主 ...
- Python基础笔记1-Python读写yaml文件(使用PyYAML库)
最近在搭建自动化测试项目过程中经常遇到yaml文件的读写,为了方便后续使用,决定记下笔记. 一,YAML 简介 YAML,Yet Another Markup Language的简写,通常用来编写项目 ...
- Python+Appium自动化测试(8)-swipe()滑动页面
app自动化测试过程中,经常会遇到滑动屏幕操作,appium框架的话我们可以使用webdriver提供的swipe()方法来对屏幕页面进行上滑.下滑.左滑.右滑操作. 一,swipe方法介绍 swip ...
- Python+Appium自动化测试(5)-appium元素定位常用方法
对于Android而言,查找appUI界面元素属性的工具有三种:appium desktop,uiautomatorviewer.bat,weditor.之前已经介绍过了weditor的使用,这里我将 ...
- pytest文档55-plugins插件开发
前言 前面一篇已经学会了使用hook函数改变pytest运行的结果,代码写在conftest.py文件,实际上就是本地的插件了. 当有一天你公司的小伙伴觉得你写的还不错,或者更多的小伙伴想要你这个功能 ...
- MySQL锁详细讲解
本文章向大家介绍MySQL锁详细讲解,包括数据库锁基本知识.表锁.表读锁.表写锁.行锁.MVCC.事务的隔离级别.悲观锁.乐观锁.间隙锁GAP.死锁等等,需要的朋友可以参考一下 锁的相关知识又跟存 ...
- centos8上使用crond
一,查看crond的状态: [root@yjweb crontab]# systemctl status crond 说明:和其他service的执行相同: 启动:systemctl start cr ...
- echo 输出颜色
shell脚本里使用echo输出颜色 echo命令颜色显示: echo: -n: 不换行. -e:让转移符生效. \t(tab) \n (换行) 实例: $ echo ...
- docker19.03使用数据卷
一,查看当前的docker版本 [root@localhost data]# docker --version Docker version 19.03.8, build afacb8b 说明:刘宏缔 ...