【Swagger】看这一篇就够了

在这里插入图片描述

各位小伙伴们大家好，欢迎跟着小扎扎一起学习【Swagger】这门技术，在本片博客中我对B站狂神的Swagger教程进行一个总结，鉴于 看到就是学到、学到就是赚到 精神，这波依然是血赚 ┗|｀O′|┛

💡Swagger知识点速览
🔊 Swagger简介
🔉 为什么使用Swagger
🔊 Swagger的配置
🔉 Spring boot集成Swagger
🔈 新建一个spring boot项目
🔈 导入两个依赖
🔈 配置Swagger
🔉 配置Swagger可扫描的接口
🔉 控制Swagger的开关
🔉 设置Swagger的分组
🔉 Swagger的各种注释
🔊 使用Swagger接口测试

🔊 Swagger简介

🔉 为什么使用Swagger

这个问题就牵涉到技术的更新迭代了，在之前的后端时代，前端只需要管理静态页面，而后端需要使用模板引擎(JSP等)去得数据并加以处理,最后显示出数据。但是随着时代的发展，开发慢慢进入了前后端分离的时代，前端和后端分成了两个相对独立的团队来合作开发，这就造成了一个问题：前后端集成联调的时候，前后端人员无法做到“及时协商，尽早解决”，最终造成问题的集中爆发。

既然已经发现问题，那么就需要使用一种解决方案来避免这个问题的干扰。做过一个完整项目的小伙伴应该都有所了解，前后端之间的协作基本上都在api接口和数据传输上，那么如果api接口能够统一、数据的格式能够一致，那么问题也就迎刃而解了。

于是Swagger应运而生，Swagger可以根据在代码中使用自定义的注解来生成接口文档,这样做的好处是在开发接口时可以通过swagger将接口文档定义好，方便前后端团队之间的协作，同时也方便以后的维护。

🔊 Swagger的配置

🔉 Spring boot集成Swagger

🔈 新建一个spring boot项目

在这里插入图片描述

🔈 导入两个依赖

<!--Swagger(开始)-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>
<!--Swagger(结束)-->

🔈 配置Swagger

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {
}

如果只是使用配置类开启Swagger的话，它的底层会有一些DEFAULT(默认)的值，开启之后就可以使用网址http://localhost:8080/swagger-ui.html来访问这个Swagger的文档界面。在这里插入图片描述当然，既然有默认的配置，我们就可以实现定制化的配置覆盖，依然是在这个配置类中进行修改

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {/***用于定制化配置Docket的bean实例*/@Beanpublic Docket Docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(ApiInfo());}/*** 定制化信息的主要设置处*/private ApiInfo ApiInfo() {// 作者的个人信息Contact contact = new Contact("作者的姓名", "作者的个人社交主页", "作者的邮箱");return new ApiInfo("标题：Swagger的测试接口文档","简介：这是一段简介，关于接口文档的简介","版本号:1.0","网页：这是一个网页链接",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList<>());}
}

修改之后的页面信息就会有一些不一样，restart项目之后重新访问ui界面
在这里插入图片描述

🔉 配置Swagger可扫描的接口

这一部分的工作也是在SwaggerConfig配置类中实现，主要就是配置哪些api接口会被Swagger生成接口文档，生成文档的api就会在swagger的ui界面上显示。通过以下.apis和.paths的配置，达到的效果就是之后在com.xiaochen.swagger.controller包下的且映射路径为/hello的才会生成对应的接口文档

 @Bean
public Docket Docket() {return new Docket(DocumentationType.SWAGGER_2).select()/*** apis就是配置哪些api可以被扫描* 主要参数可以包括：*  - RequestHandlerSelectors.basePackage()：指定可以扫描的包 参数是包(package)名*  - RequestHandlerSelectors.any()：扫描所有*  - RequestHandlerSelectors.none()：都不扫描*  - RequestHandlerSelectors.withClassAnnotation()：扫描类上注解  参数是注解类的反射对象，eg:@RestController.class*  - RequestHandlerSelectors.withMethodAnnotation()扫描方法上注解  参数是注解类的反射对象，eg:@RequestMapping.class*/.apis(RequestHandlerSelectors.basePackage("com.xiaochen.swagger.controller"))/*** paths就是配置哪些映射路径下的api可以被扫描* 主要参数可以包括：*  - PathSelectors.ant()：指定映射路径 主要就是斜杠+单词或者通配符*  - PathSelectors.any()：扫描所有*  - PathSelectors.none()：都不扫描*  - PathSelectors.regex()：扫描符合正则的所有路径*/.paths(PathSelectors.ant("/hello")).build().apiInfo(ApiInfo());
}

🔉 控制Swagger的开关

使用.enable可以控制Swagger的开关，如果关闭了Swagger的话就会导致ui界面无法打开，也就无法查看接口文档
在这里插入图片描述那么该如何实现只在开发和测试阶段开启Swagger呢？首先应该先预设一下想要开启的项目环境，通过Environment 对象来监听项目的环境与预设的是否一致，最后使用.enable控制Swagger的开关

@Bean
public Docket Docket(Environment environment) {// 预设的项目环境(可设置多个)Profiles profiles = Profiles.of("dev", "test");// 监听项目的环境与预设的是否一致boolean flag = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2).enable(flag);
}

🔉 设置Swagger的分组

在没有设置Swagger的分组之前，有一个默认的default分组，分组个数的多少就取决于SwaggerConfig 配置类中有多少个Docket 实例，值得注意的是：不能出现同名的分组，即使是未命名的分组(也就是default)也不能重复出现，否则就会报java.lang.IllegalStateException异常在这里插入图片描述