前面已经介绍过了Swagger的基础使用了

下面继续分别详细说明下 不添加版本控制以及添加版本控制的使用情况，其实也基本一致，对看起来可能更加容易理解

第一步 导入nuget包

nuget导入Swashbuckle.AspNetCore (对应有Swashbuckle.AspNetCore.Swagger、Swashbuckle.AspNetCore.SwaggerGen、Swashbuckle.AspNetCore.SwaggerUI)

版本控制还需要引入

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

Microsoft.AspNetCore.Mvc.Versioning

第二步 添加服务及配置

下面代码中都结合了IdentityServer4中的相关设置，可以忽略

非版本控制

ConfigServices中添加如下代码

  1. services.AddSwaggerGen(options =>
  2.             {
  3.                 options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info
  4.                 {
  5.                     Version = "v1.0",
  6.                    Title = "体检微服务接口"
  7.                 });
  8.  
  9.                 var basePath = PlatformServices.Default.Application.ApplicationBasePath;
  10.                 var xmlPath = Path.Combine(basePath, "ExaminationServicesApi.xml");
  11.                 options.IncludeXmlComments(xmlPath);
  12.  
  13.                 var xmlmodelPath =
  14.                 Path.Combine(basePath, "ExaminationServicesDomain.xml");
  15.                 options.IncludeXmlComments(xmlmodelPath);
  16.  
  17.                 #region Swagger添加授权验证服务
  18.  
  19.                 //options.AddSecurityDefinition("Bearer", new ApiKeyScheme
  20.                 //{
  21.                 //    Description = "JWT Bearer 授权 \"Authorization: Bearer+空格+token\"",
  22.                 //    Name = "Authorization",
  23.                 //    In = "header",
  24.                 //    Type = "apiKey"
  25.                 //});
  26.  
  27.                 options.AddSecurityDefinition("oauth2", new OAuth2Scheme
  28.                 {
  29.                     Type = "oauth2",
  30.                     Flow = "implicit",
  31.                     AuthorizationUrl = _authorityconfig.Authority + "/connect/authorize",
  32.                     Scopes = new Dictionary<string, string>
  33.                         {
  34.                           //{ "openid", "身份信息" } ,
  35.                           //{ "profile", "个人基本信息" } ,
  36.                           { "userservicesapi", "用户服务" },
  37.                           { "examinationservicesapi", "体检服务" }
  38.                         }
  39.                 });
  40.                 options.OperationFilter<CustomOperationFilter>();
  41.                 #endregion
  42.  
  43.             });
  1.  app.UseSwagger();
  2.             app.UseSwaggerUI(c =>
  3.             {
  4.                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi");
  5.                 c.OAuthClientId("testuserservicesapiexaminationservicesapi");
  6.                 c.OAuthAppName("体检服务");
  7.             });

这里要注意到我添加了2个xml 一个是apicontroller的获取注释描述，如果需要model相关的描述可以将model所在的应用程序集xml处理下，以便于在接口文档上可以看到model的先关说明

版本控制

ConfigServices中添加如下代码 只不过是动态的处理了版本信息

  1.  services.AddApiVersioning(option =>
  2.             {
  3.                 option.AssumeDefaultVersionWhenUnspecified = true;
  4.                 option.ReportApiVersions = false;
  5.             })
  6.             .AddMvcCore().AddVersionedApiExplorer(option => {
  7.                 option.GroupNameFormat = "'v'VVV";
  8.                 option.AssumeDefaultVersionWhenUnspecified = true;
  9.             });
  10.             services.AddSwaggerGen(options =>
  11.             {
  12.                 var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
  13.                 foreach (var description in provider.ApiVersionDescriptions)
  14.                 {
  15.                     options.SwaggerDoc(description.GroupName,
  16.                          new Info()
  17.                         {
  18.                             Title = $"体检微服务接口 v{description.ApiVersion}",
  19.                             Version = description.ApiVersion.ToString(),
  20.                             Description = "切换版本请点右上角版本切换",
  21.                             Contact = new Contact() { Name = "黎又铭", Email = "2939828886@qq.com" }
  22.                         }
  23.                     );
  24.                 }
  25.  
  26.                 //options.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info
  27.                 //{
  28.                 //    Version = "v1.0",
  29.                 //    Title = "体检微服务接口"
  30.                 //});
  31.  
  32.                 var basePath = PlatformServices.Default.Application.ApplicationBasePath;
  33.                 var xmlPath = Path.Combine(basePath, "ExaminationServicesApi.xml");
  34.                 options.IncludeXmlComments(xmlPath);
  35.  
  36.                 var xmlmodelPath =
  37.                 Path.Combine(basePath, "ExaminationServicesDomain.xml");
  38.                 options.IncludeXmlComments(xmlmodelPath);
  39.  
  40.                 #region Swagger添加授权验证服务
  41.  
  42.                 //options.AddSecurityDefinition("Bearer", new ApiKeyScheme
  43.                 //{
  44.                 //    Description = "JWT Bearer 授权 \"Authorization: Bearer+空格+token\"",
  45.                 //    Name = "Authorization",
  46.                 //    In = "header",
  47.                 //    Type = "apiKey"
  48.                 //});
  49.  
  50.                 options.AddSecurityDefinition("oauth2", new OAuth2Scheme
  51.                 {
  52.                     Type = "oauth2",
  53.                     Flow = "implicit",
  54.                     AuthorizationUrl = _authorityconfig.Authority + "/connect/authorize",
  55.                     Scopes = new Dictionary<string, string>
  56.                         {
  57.                           //{ "openid", "身份信息" } ,
  58.                           //{ "profile", "个人基本信息" } ,
  59.                           { "userservicesapi", "用户服务" },
  60.                           { "examinationservicesapi", "体检服务" }
  61.  
  62.                         }
  63.                 });
  64.                 options.OperationFilter<CustomOperationFilter>();
  65.                 #endregion
  66.  
  67.             });
  1.  app.UseSwagger();
  2.             app.UseSwaggerUI(c =>
  3.             {
  4.  
  5.                 foreach (var description in provider.ApiVersionDescriptions)
  6.                 {
  7.                     c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
  8.                 }
  9.                 //c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi");
  10.                 c.OAuthClientId("testuserservicesapiexaminationservicesapi");
  11.                 c.OAuthAppName("体检服务");
  12.             });

对比两种情况可以看出实际上就多出来一个办理版本信息而已，ApiVersionDescriptions 其实就是通过这个特性动态遍历了版本信息，所以多版本控制只需要在ApiController中添加好相关的属性标签即可

第三步 使用

  1. [ApiVersion("1.0")]
  2. [Route("api/v{api-version:apiVersion}/[controller]")]
  3.  public class DemoController : ControllerBase
  4. {
  5.  
  6. }

在前面代码中我们用到了 CustomOperationFilter这个处理，在这个操作过滤器中我在之前的代码中添加授权及文件上传，这里我们使用版本控制还需要在里面添加好版本参数描述处理

  1.  public class CustomOperationFilter : IOperationFilter
  2.     {
  3.         public void Apply(Operation operation, OperationFilterContext context)
  4.         {
  5.  
  6.             #region Swagger版本描述处理
  7.             foreach (var parameter in operation.Parameters.OfType<NonBodyParameter>())
  8.             {
  9.                 var description = context.ApiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);
  10.  
  11.                 if (parameter.Description == null)
  12.                 {
  13.                     parameter.Description = description.ModelMetadata.Description;
  14.                 }
  15.             }
  16.  
  17.             #endregion
  18.  
  19.             #region Swagger授权过期器处理
  20.             if (operation.Security == null)
  21.                 operation.Security = new List<IDictionary<string, IEnumerable<string>>>();
  22.             var oAuthRequirements = new Dictionary<string, IEnumerable<string>>
  23.                                         {
  24.  
  25.                                               {"oauth2", new List<string> { "openid", "profile", "examinationservicesapi" }}
  26.                                         };
  27.             operation.Security.Add(oAuthRequirements);
  28.             #endregion
  29.  
  30.             #region Swagger 文件上传处理
  31.  
  32.             var files = context.ApiDescription.ActionDescriptor.Parameters.Where(n => n.ParameterType == typeof(IFormFile)).ToList();
  33.             if (files.Count > )
  34.             {
  35.                 for (int i = ; i < files.Count; i++)
  36.                 {
  37.                     if (i == )
  38.                     {
  39.                         operation.Parameters.Clear();
  40.                     }
  41.                     operation.Parameters.Add(new NonBodyParameter
  42.                     {
  43.                         Name = files[i].Name,
  44.                         In = "formData",
  45.                         Description = "Upload File",
  46.                         Required = true,
  47.                         Type = "file"
  48.                     });
  49.  
  50.                 }
  51.                 operation.Consumes.Add("multipart/form-data");
  52.             }
  53.  
  54.             #endregion
  55.         }
  56.     }

运行程序看效果

版本控制就搞定了，这里需要说明的是看下面的图

额外说明

版本是不是必须的、以及描述就是在CustomOperationFilter中处理下默认的说明，你可以这样写

  1.  if (parameter.Description == null)
  2.                 {
  3.                     parameter.Description ="填写版本号如:1.0";
  4.                 }
  5.  
  6. parameter.Required=false; //设置非必填或非必填

下面看下效果，已经有注释了和设置了的非必填项目

这里额外在说一点的就是

  1.  [ApiVersion("1.0", Deprecated = false)]

Deprecated  这个属性设置 True ：标识是否弃用API ,在设置为true的情况下来看下效果

1.0版本已经是弃用了，这里又要额外说下与这个关联的属性了就是在服务配置选项中的 ReportApiVersions 设置 用下面的配置

  1.  services.AddApiVersioning(option =>
  2.             {
  3.                 option.ReportApiVersions = false;
  4.             })
  5.             .AddMvcCore().AddVersionedApiExplorer(option => {
  6.                 option.GroupNameFormat = "'v'VVV";
  7.                 option.AssumeDefaultVersionWhenUnspecified = true;
  8.                 option.DefaultApiVersion = new ApiVersion(, );
  9.             });

false:不再请求响应中添加 版本报告信息，下图中已经不会显示我一用的版本信息了

上面默认版本 DefaultApiVersion 我设置了1.0 在代码中出现2个版本路由地址一样，在没有填写版本号的情况下使用默认版本

AssumeDefaultVersionWhenUnspecified：true 是否在没有填写版本号的情况下使用默认版本

  1.  

.NetCore使用Swagger进行单版本或多版本控制处理的更多相关文章

  1. .NetCore WebApi —— Swagger版本控制

    目录: .NetCore WebApi——Swagger简单配置 .NetCore WebApi——基于JWT的简单身份认证与授权(Swagger) .NetCore WebApi —— Swagge ...

  2. .NetCore WebApi——Swagger简单配置

    在前后端分离的大环境下,API接口文档成为了前后端交流的一个重点.Swagger让开发人员摆脱了写接口文档的痛苦. 官方网址:https://swagger.io/ 在.Net Core WebApi ...

  3. 为.netcore助力--WebApiClient正式发布core版本

    1 前言 WebApiClient已成熟稳定,发布了WebApiClient.JIT和WebApiClient.AOT两个nuget包,累计近10w次下载.我对它的高可扩展性设计相当满意和自豪,但We ...

  4. Centos 7上安装Python3.x（单版本）

    Centos7默认安装的是2.7,这里选择安装使用Python3.6.3 安装Python3.6.3 1.安装python3 需要的依赖包 yum install -y openssl-devel b ...

  5. netcore 添加swagger

    1.添加相应的nuget包  2.配置服务和swaggerui startup.cs 中 configureServices 中添加下面代码: //swagger services.AddSwagge ...

  6. 跟我一起学.NetCore之Swagger让前后端不再烦恼及界面自定义

    前言 随着前后端分离开发模式的流行,接口对接.联调成为常事,前端同事会经常问:我需要调哪个接口?这个接口数据格式是啥?条件都传啥? 对于一些紧急接口可能会采取沟通对接,然后补文档,其他的都会回一句:看 ...

  7. .NetCore利用Swagger生成 XML文档需要注意生成路径的地址

    发布的时候如果用 release dotnet publish --configuration release dotnet publish 默认都是debug 会出现 XML丢失问题,其实可以看下工 ...

  8. 利用swagger和API Version实现api版本控制

    场景: 在利用.net core进行api接口开发时,经常会因为需求,要开发实现统一功能的多版本的接口.比如版本V1是给之前用户使用,然后新用户有新需求,这时候可以单独给这个用户写接口,也可以在V1基 ...

  9. NetCore 3.0 中使用Swagger生成Api说明文档及升级报错原因

    认识Swagger Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参 ...

随机推荐

  1. Linux_MySql_tar_安装（转）

    系统版本:CentOs 7.* Mysql版本:5.7.17(自己测试版本) 根据博主[大大的橙子]博文转载记录(大部分照搬了,只修改少许部分) 一.基本环境部署 #卸载系统自带的Mariadb [r ...

  2. Docker一些常用命令

    1.启动Docker服务 service docker start 2.查看所有镜像 docker images 3.查看正在运行的容器 docker ps 4.查看所有容器 docker ps -a ...

  3. BZOJ2326 HNOI2011数学作业（矩阵快速幂）

    考虑暴力,那么有f(n)=(f(n-1)*10digit+n)%m.注意到每次转移是类似的,考虑矩阵快速幂.首先对于位数不同的数字分开处理,显然这只有log种.然后就得到了f(n)=a·f(n-1)+ ...

  4. MT【203】连续型的最值

    (北大自招)已知$-6\le x_i\le 10 (i=1,2,\cdots,10),\sum\limits_{i=1}^{10}x_i=50,$当$\sum\limits_{i=1}^{10}x^2 ...

  5. emoji表情存储到数据库的方法

    方案1:修改数据库编码 为什么我们设置表的的字符类型为utf8却不能存放emoji呢?原来utf8可能是2或3或4个字节,而mysql的utf8是3个字节,存放一个emoji是需要4个字节的,自然不够 ...

  6. HDU 6153 扩展kmp

    A Secret Time Limit: 2000/1000 MS (Java/Others)    Memory Limit: 256000/256000 K (Java/Others)Total ...

  7. indeed招聘

    https://cn.indeed.com/%E5%B7%A5%E4%BD%9C-%E4%BA%BA%E5%B7%A5%E6%99%BA%E8%83%BD%E5%85%AC%E5%8F%B8-%E5% ...

  8. python---django中模板布局

    对于页面大部分一样,我们可以使用模板布局来简化 可以查看tornado中的模板引擎,基本一致 python---tornado模板引擎 对于相同代码部分,我们可以提取出来,放在布局文件layout.p ...

  9. MyBatis中传入参数parameterType类型详解

    前言 Mybatis的Mapper文件中的select.insert.update.delete元素中有一个parameterType属性,用于对应的mapper接口方法接受的参数类型.本文主要给大家 ...

  10. POJ - 3026 Borg Maze（最小生成树）

    https://vjudge.net/problem/POJ-3026 题意 在一个y行 x列的迷宫中,有可行走的通路空格’ ‘,不可行走的墙’#’,还有两种英文字母A和S,现在从S出发,要求用最短的 ...