一、什么是Swagger?为什么要使用Swagger?

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

　　我们之前通过Word、Excel手动编写的接口文档，大家有没有遇到以下情况：

• 前端经常抱怨后端给的接口文档与实际情况不一致；
• 后端觉得编写及维护接口文档会耗费不少精力，经常来不及或忘记更新；

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

二、引用和配置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

三、为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

• 这样运行项目后，注释都有了，非常完美。如下：