一、什么是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

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

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

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

二、引用和配置Swagger

三、为SwaggerUI接口添加注释

猜你喜欢