Springboot基础学习之（二十一):Swagger基础学习(swagger信息介绍，配置扫描接口和开关，分组和接口注释）
什么是Swagger？
Swagger2是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful 风格的Web 服务
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。
为什么要使用Swagger？
1：Swagger可以实现注释信息的添加，帮助我们更好的了解到接口信息
2：可以实现接口文档的实时更新
3：通过Swagger接口可以实现在线测试与app postman相似
实施Swagger结构
一：创建一个springboot项目环境(web）
二：导入swagger2需要使用的依赖
io.springfox
springfox-swagger2
3.0.0
io.springfox
springfox-swagger-ui
3.0.0
io.springfox
springfox-boot-starter
3.0.0
三：在配置文件对路径进行配置
Springboot2.6以后将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHERSwagger页面的路径
package springfox.boot.starter.autoconfigure;
import org.springframework.util.StringUtils;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
// tag::swagger-ui-configurer[]
public class SwaggerUiWebMvcConfigurer implements WebMvcConfigurer {
private final String baseUrl;
public SwaggerUiWebMvcConfigurer(String baseUrl) {
this.baseUrl = baseUrl;
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
String baseUrl = StringUtils.trimTrailingCharacter(this.baseUrl, '/');
registry.
addResourceHandler(baseUrl + "/swagger-ui/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
.resourceChain(false);
}
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addViewController(baseUrl + "/swagger-ui/")
.setViewName("forward:" + baseUrl + "/swagger-ui/index.html");
}
}
// end::swagger-ui-configurer[]
由SwaggerUiWebMvcConfigurer类可知我们要访问上图中index页面
路径为：http://localhost:8080/swagger-ui/index.html
注意：一定要查看依赖中的路径配置，因为不同版本的swagger导致index页面不一样和访问路径也可能不同
四：启动swagger：定义个类swagger_config实现swagger功能的开启
@Configuration
@EnableSwagger2
public class swagger_config {
}
执行项目：访问swagger后台界面
这个界面就是swagger2的后台界面，可以从这里看到关于后端配置的一些信息。以及通过此页面可以进行在线测试，测试网页的实现是否出现Bug
配置swagger：在swagger_config类进行配置
修改这个网页上的输出内容
@Configuration
@EnableSwagger2
public class swagger_config {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).groupName("不想").apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
Contact contact = new Contact("不想睡醒的梦", "https://blog.csdn.net/m0_52479012?spm=1000.2115.3001.5343", "[email protected]");
return new ApiInfo("不想睡醒的梦",
"不想睡醒的梦",
"不想睡醒的梦",
"https://blog.csdn.net/m0_52479012?spm=1000.2115.3001.5343",
contact, "Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
运行项目查看网页显示的内容是否发生改变
这就是配置完成后的内容
如何查看后端的访问
创建一个controller类，定义个方法访问
@RestController
public class Mycontroller1 {
@GetMapping("/")
public String swagger(){
return "swagger";
}
}看看在swagger页面是否显示信息
获取到方法如何在这个网页实现在线测试呢？
点击绿色框
点击蓝色按钮
点击Excute按钮
然后出现的内容就是这个域名访问的具体信息
配置swagger扫描的接口以及开关
进行组的配置
在实际的开发过程中，一个swagger页面不可能只有一个人进行使用，所以要设置多个组
@Configuration
@EnableSwagger2
public class swagger_config {
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("b");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("v");
}
}可以在不同组进行不同的配置信息
配置扫描接口：在docket容器中实现配置
主要的配置信息就一行代码
RequestHandlerSelectors配置要扫描接口的方式 basePackage设置扫描包的位置 any都进行扫描 none全都不进行扫描 .withClassAnnotation(Controller.class) 扫描类上的注解 withMethodAnnotation(GetMapping.class)扫描方法上的注解
完整代码
@Configuration
@EnableSwagger2
public class swagger_config {
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("b");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("v");
}
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2).groupName("不想睡醒的梦").apiInfo(apiInfo())
// .enable(true) //控制swagger是否开启
.select()
.apis(RequestHandlerSelectors.none())
//paths过滤ant则是指定路径进行过滤
// .paths(PathSelectors.ant("/demo/**"))
.build();
}
private ApiInfo apiInfo(){
Contact contact = new Contact("不想睡醒的梦", "https://blog.csdn.net/m0_52479012?spm=1000.2115.3001.5343", "[email protected]");
return new ApiInfo("不想睡醒的梦",
"不想睡醒的梦",
"不想睡醒的梦",
"https://blog.csdn.net/m0_52479012?spm=1000.2115.3001.5343",
contact, "Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
接口的配置决定我们能够获取到怎么样的配置内容
当前组（ 不想睡醒的梦）接口现在的配置为None
运行项目
没有任何的信息
但当我们切换组时
发现不同组配置不同，出现的内容不同这就是组所带来的好处
通过.enable控制swagger的开关
在v这个组关闭swagger功能
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("v")
.enable(false);
}关闭就不进行显示
全都关闭又是怎样的呢？
除了开关和扫描配置还有一个关键配置：过滤
将指定文件给过滤调，不进行扫描
没有进行过滤配置之前
配置代码：
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2).groupName("不想睡醒的梦").apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
// paths过滤ant则是指定路径进行过滤
.paths(PathSelectors.ant("/demo/**"))
.build();
}没有扫描到能够使用的API：将内容成功过滤
如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？
还是在Docket容器中进行配置（dev和test环境可以进行访问）
@Bean
public Docket docket(Environment environment){
Profiles of = Profiles.of("dev", "test");
//设置要显示的环境
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2).groupName("不想睡醒的梦").apiInfo(apiInfo())
.enable(b) //控制swagger是否开启
.select()
.apis(RequestHandlerSelectors.any())
.build();
}环境搭建
当前环境为dev访问swagger
访问成功
修改环境
禁止访问，配置成功
配置实体类：如何被扫描到显示在swagger中
创建一个实现类
package com.swagger.demo.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户参数类") //注解：类型解释
public class user {
@ApiModelProperty("用户名") //未定义的属性，添加一个注解
public String name;
@ApiModelProperty("属性id")
public String id;
}
创建一个接口并映射在这个实体类上
@GetMapping("/user")
public user swagger1(){
return new user();
}注意：
注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释
实体类添加成功：
关于swagger常用注解
除此只要还可以在接口中进行注解解释
@ApiOperation("你好") //默认注释是方法名，如果添加这个注解，进行替换
@GetMapping("/hello")
public String hello(@ApiParam("用户名") String name){
return "hello"+name;
}