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

一、什么是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的配置及使用

  • 我们输入/Swagger可以正常进入SwaggerUI页面,接下来我们把默认路由指向SwaggerUI页面。打开launchSettings.json修改如下:

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

  • 这样我们运行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的配置及使用  

上一篇:Case Study的基本概念以及写作的常识介绍


下一篇:DNS解析综合学习案例