【我的学习】: Swagger的配置及使用

时间 2020-06-03 标签我的学习 swagger 配置使用

1、什么是Swagger?为何要使用Swagger?

　　Swagger 是一个规范和完整的框架，如今愈来愈多的项目采用先后端分离，API成了后端与前端沟通的纽带，API的文档也变得愈来愈重要。使得这个集文档在线自动生成+美观+测试于一身的框架Swagger愈来愈受欢迎。前端

　　咱们以前经过Word、Excel手动编写的接口文档或者说是第三方的api文档管理工具（小幺鸡等），你们有没有遇到如下状况：shell

前端常常抱怨后端给的接口文档与实际状况不一致；
后端以为编写及维护接口文档会耗费很多精力，常常来不及或忘记更新；

　　Swagger完美（这就跟开发平常的开发习惯息息相关了，要及时更新代码注释）解决了以上的问题，Swagger在API开发新版本或者迭代版本的时候，只须要更新Swagger描述文件，就能够自动生成接口文档和客户端服务端代码，作到调用端代码、服务端代码以及接口文档的一致性；json

2、引用和配置Swagger

经过工具-->NutGet包管理器-->程序包管理器控制台添加Swagger插件 shell命令以下：install-package Swashbuckle.AspNetCore -version 4.0.1 -Study.NetCore
打开项目的NetCore项目的Startup.cs类（程序入口）配置Swagger，以下：

#region Swagger配置 services.AddSwaggerGen(swg => { swg.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Version = "v1", Title = "Study.NetCore API", Description = "API-说明文档", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Study.NetCore", Email = "", Url = "" } }); }); #endregion

在Configure类中启动Swagger中间件，以下：

#region 启动Swagger app.UseSwagger(); app.UseSwaggerUI(swg => { swg.SwaggerEndpoint("/swagger/v1/swagger.json", "APIExplainDoc"); }); #endregion

启动项目，咱们能够看到页面直接进入了以下的页面：

咱们输入/Swagger能够正常进入SwaggerUI页面，接下来咱们把默认路由指向SwaggerUI页面。打开launchSettings.json修改以下：

这样咱们运行Swagger项目，默认打开的就是SwaggerUI页面；
若是要发布到正式环境，就会发现，上边的那种默认启动首页无效了，仍是须要咱们每次手动在域名后边输入 /swagger，这时咱们在Configure中配置swg.RoutePrefix =“” 以下：
```
#region 启动Swagger app.UseSwagger(); app.UseSwaggerUI(swg => { swg.SwaggerEndpoint("/swagger/v1/swagger.json", "APIExplainDoc"); swg.RoutePrefix = ""; }); #endregion
```

3、为SwaggerUI接口添加注释

右键项目名称-->属性-->生成-->勾选XML文档文件，勾选XML文档文件以后，经过修改ConfigureServices让项目启动时读取这个Xml文件，以下：

#region Swagger配置 services.AddSwaggerGen(swg => { swg.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Version = "v1", Title = "Study.NetCore API", Description = "API-说明文档", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Study.NetCore", Email = "", Url = "" } }); var bashPath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(bashPath, "Study.NetCore.xml"); swg.IncludeXmlComments(xmlPath, true);//这个是controller的注释  }); #endregion

这样运行项目后，注释都有了，很是完美。以下：

添加实体类的说明：基本和api的配置一致，首先勾选XML文档文件，而后在ConfigureServices中修改swagger配置，以下：后端

#region Swagger配置 services.AddSwaggerGen(swg => { swg.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Version = "v1", Title = "Study.NetCore API", Description = "API-说明文档", TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Study.NetCore", Email = "", Url = "" } }); var bashPath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(bashPath, "Study.NetCore.xml"); swg.IncludeXmlComments(xmlPath, true);//这个是controller的注释 //model的Xml文件
                var xmlModelPath = Path.Combine(bashPath, "Study.NetCore.Model.xml"); swg.IncludeXmlComments(xmlModelPath); }); #endregion

若是要隐藏某个接口，直接在action或controller上添加特性[ApiExplorerSettings(IgnoreApi = true)]

4、版本控制

　　说到版本控制，咱们第一时间想到的是Git、SVN等的源代码版本管理器，版本控制，顾名思义，就是对程序代码，文件等的变动管理，多个版本保证代码更改后有迹可循，可实时恢复以前版本；这就是项目的版本控制，而咱们今天说的是对API的版本控制，下面咱们借助swagger实现对api的版本控制。api

首先先建一个用于区分版本的枚举类以下：

namespace Study.NetCore.SwaggerHelper { /// <summary>
    /// 版本控制 /// </summary>
    public class VersionControl { /// <summary>
        /// 接口版本号 /// </summary> 
        public enum ApiVersion { /// <summary>
            /// v1版本 /// </summary>
            v1 = 1, /// <summary>
            /// v2版本 /// </summary>
            v2 = 2, } } }

接下来，咱们打开StartUp.cs类，在ConfigureServices配置中心，修改Swagger的配置以下：


            private const string apiName = "Study.NetCore";
　　 #region Swagger配置
            var bashPath = PlatformServices.Default.Application.ApplicationBasePath; services.AddSwaggerGen(swg => { //遍历版本号展现
                typeof(ApiVersion).GetEnumNames().ToList().ForEach(version => { swg.SwaggerDoc(version, new Swashbuckle.AspNetCore.Swagger.Info { Version = version, Title = $"{apiName} API", Description = $"{apiName} API" + version, TermsOfService = "None", Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = $"{apiName}", Email = "", Url = "" } }); }); var xmlPath = Path.Combine(bashPath, "Study.NetCore.xml"); swg.IncludeXmlComments(xmlPath, true);//这个是controller的注释

                var xmlModelPath = Path.Combine(bashPath, "Study.NetCore.Model.xml");//model的Xml文件
 swg.IncludeXmlComments(xmlModelPath); }); #endregion

接着，找到配置启动项的方法configure，修改Swagger启动代码以下：

#region 启动Swagger app.UseSwagger(); /* * 以前只有一个版本，因此固定写死 * 遍历接口版本，并倒叙展现 */ app.UseSwaggerUI(swg => { typeof(ApiVersion).GetEnumNames().OrderByDescending(ver => ver).ToList().ForEach(version => { swg.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"StudyNetCore API {version}"); swg.RoutePrefix = ""; }); }); #endregion

运行以下（借助Swagger来实现对API多版本的展现）以下：

自定义路由，新建ApiRouteAttribute特性类，以下：

namespace Study.NetCore.SwaggerHelper { /// <summary>
    /// 自定义路由 /api/{version}/[controler]/[action] /// </summary>
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class ApiRouteAttribute : RouteAttribute, IApiDescriptionGroupNameProvider { /// <summary>
        /// 分组名称,是来实现接口 IApiDescriptionGroupNameProvider /// </summary>
        public string GroupName { get; set; } /// <summary>
        /// 自定义路由构造函数，继承基类路由 /// </summary>
        /// <param name="actionName"></param>
        public ApiRouteAttribute(string actionName = "[action]") : base("/api/{version}/[controller]/" + actionName) { } ///// <summary>
        /// 自定义版本+路由构造函数，继承基类路由 /// </summary>
        /// <param name="actionName"></param>
        /// <param name="version"></param>
        public ApiRouteAttribute(ApiVersion version, string actionName = "") : base($"/api/{version.ToString()}/[controller]/{actionName}") { GroupName = version.ToString(); } } }

接口版本控制的使用

对要区分版本的接口添加特性如:

namespace Study.NetCore.Controllers { [Route("api/[controller]")] [ApiController] public class ValuesController : ControllerBase { /// <summary>
        /// 测试注释有没有加上1 /// </summary>
        /// <returns></returns>
 [HttpGet] public ActionResult<IEnumerable<string>> Get() { return new string[] { "value1", "value2" }; } [HttpGet] //和上边的版本控制以及路由地址都是同样的
        [ApiRouteAttribute(ApiVersion.v2, "TestV2")] public string TestV2() { return "我是老二"; } [HttpGet("Test")] public string Test() { return "我是老大"; } } }

对要区分同名的接口：在 controller 文件夹下，新建两个文件夹， v一、v2，而后添加相同的接口控制器，自定义便可，以下：
运行，切换swaggerUI 版本查看。