SpringBoot集成Swagger2、Swagger2和Swagger3的区别Swagger的注解学习

Swagger的介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
随着前后端技术的日渐成熟，前后端的交互就只有接口了，前端请求接口获取数据，所以接口的格式化也就相当重要，有一个标准格式的接口文档在开发过程中是相当重要的，swagger就是这么一个在线的接口文档，在SpringBoot的集成之中也相当便利。
swagger可以自动生成在线接口文档，界面可视化的同时保证了便利的测试接口。
SpringBoot项目集成Swagger2的步骤：
1）导入Maven的坐标
2）书写Swagger的配置文件类
3）访问Swagger的UI界面
导入maven坐标

<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>

swagger2的配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;
/*** @ClassName: Swagger3Config* @Description:(描述这个类的作用)* @author: 曾石头* @date: 2022/8/23 13:03* @Version 1.0*/
@EnableOpenApi
@Configuration
public class Swagger3Config {//配置swagger的Docket的bean实例@Beanpublic Docket docket(Environment environment){//配置要显示的swagger环境Profiles profiles = Profiles.of("dev","test");//判断是否处再自己设定的环境当中boolean flag = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())//swagger开关.enable(flag).groupName("项目组名称").select()//RequestHandlerSelectors,配置要扫描接口的方式//basePackage() 指定要扫描的包//none()不扫描//withClassAnnotation 扫描类上的注解//withMethodAnotation 扫描方法上的注解.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))//paths()过滤什么路径//paths(PathSelectors.ant("/demo/**")).build();}//配置Swagger信息 apiInfoprivate ApiInfo apiInfo() {//作者信息Contact contact = new Contact("曾石头", "无", "无");return new ApiInfo("项目的api文档","启点视频项目的描述","1.0","无",contact, "Apache 2.0","无",new ArrayList());}
}

@EnableSwagger2 注解的作用是自动开启swagger2
@ApiOperation 注解来判断是否生成api文档
@ApiImplicitParam 注解的属性值
1.单个参数的方法

@RestController
@RequestMapping("/Test")
@Api("测试swagger接口")
public class TestController {@RequestMapping(path = "/getStudent",method = RequestMethod.GET)@ApiOperation("/根据学生id获取学生信息")@ApiImplicitParam(name = "id",value = "id",required = true,paramType = "query",dataType = "int",dataTypeClass = Integer.class)public Student getStudent(@RequestParam Integer id){Student student = new Student();student.setId(11);student.setAge(21);Map<Integer,Student> studentMap = new HashMap<>();studentMap.put(11,student);return studentMap.get(id);}
}

2.多个参数的方法

@RequestMapping(path = "/getStudent",method = RequestMethod.PATCH)
@ApiOperation("/根据学生id获取学生信息")
@ApiImplicitParams({@ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query",dataType = "String",dataTypeClass = String.class),@ApiImplicitParam(name = "age",value = "年龄",required = true,paramType = "query",dataType = "int",dataTypeClass = Integer.class)
})
public Student editStudent(@RequestParam String name, @RequestParam Integer age){Student student = new Student();student.setId(12);student.setName(name);student.setAge(age);return student;}

注意：需要对多个参数进行属性说明时，需要用到 @ApiImplicitParams，然后里面再用 @ApiImplicitParam。
参数是对象的用法

@ApiOperation("/添加学生信息")@RequestMapping(path = "/addStudent",method = RequestMethod.POST)public Map<Integer,Student> AddStudent(@RequestBody Student student){Map<Integer,Student> studentMap = new HashMap<>();studentMap.put(student.getId(),student);return studentMap;}

实体类entity

/*** (Student)实体类*/
@ApiModel("学生类")
public class Student {/*** 唯一标识id*/@ApiModelProperty("id")private Integer id;/*** 姓名*/@ApiModelProperty("姓名")private String name;/*** 年龄*/@ApiModelProperty(value = "年龄")private Integer age;
}

@ApiModelProperty 的属性配置相对之前那个@ApiImplicitParam的属性更多更全。
浏览器访问：localhost:8091/swagger-ui.html

Swagger2和Swagger3的区别
1）导入依赖
Swagger2

<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>

Swagger3

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

2）注解的启用
Swagger2: @EnableSwagger2
Swagger3: @EnableOpenApi

3）页面的位置
Swagger2: http://localhost:8080/swagger-ui.html
Swagger3: http://localhost:8080/swagger-ui/
注意：最后的斜杠不能省略
4）配置类的区别
Swagger2

return new Docket(DocumentationType.SWAGGER_2)

Swagger3

return new Docket(DocumentationType.OAS_30)

v2 和v3 使用的文档注解都是相同的

Swagger的注解说明

@Api ：请求类的说明

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。tags="说明该类的作用"value="该参数没什么意义，所以不需要配置"

@ApiOperation 注解说明

@ApiOperation："用在请求的方法上，说明方法的作用"value="说明方法的作用"notes="方法的备注说明"

@ApiImplicitParams @ApilmplicitParam

@ApiImplicitParams：用在请求的方法上，包含一组参数说明@ApiImplicitParam：对单个参数的说明        name：参数名value：参数的汉字说明、解释required：参数是否必须传paramType：参数放在哪个地方· header --> 请求参数的获取：@RequestHeader· query --> 请求参数的获取：@RequestParam· path（用于restful接口）--> 请求参数的获取：@PathVariable· body（请求体）-->  @RequestBody User user· form（普通表单提交）       dataType：参数类型，默认String，其它值dataType="Integer"       defaultValue：参数的默认值

@ApiResponses @ApiResponse

@ApiResponses：方法返回对象的说明@ApiResponse：每个参数的说明code：数字，例如400message：信息，例如"请求参数没填好"response：抛出异常的类

@ApiModel 用于JavaBean上，表示一个JavaBean的信息

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）

@ApiModelProperty 用于JavaBean类的属性上说明属性的含义

@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{@ApiModelProperty(value = "是否成功")private boolean success=true;@ApiModelProperty(value = "返回对象")private Object data;@ApiModelProperty(value = "错误编号")private Integer errCode;@ApiModelProperty(value = "错误信息")private String message;/* getter/setter 略*/
}

SpringBoot使用拉截器后，放行Swagger

Swagger请求的路径：
1）http://localhost/swagger-resources/configuration/ui
2）http://localhost/swagger-resources/configuration/security
3）http://localhost/swagger-resources
4）http://localhost/v3/api-docs?group=%E5%90%AF%E7%82%B9%E6%8A%80%E6%9C%AF%E4%BA%8C%E7%BB%84
注意：Swagger2 这里用"/v2/" Swagger3 这里用"/v3/"

@Configuration
public class WebConfiguration implements WebMvcConfigurer{//实现的拉截器 extends HandlerInterceptorAdapter@Autowiredprivate  LoginInterceptor  loginInterceptor;/*** 解决跨域问题*/@Overridepublic void addCorsMappings(CorsRegistry registry) {registry.addMapping("/**").allowedHeaders("*").allowedMethods("*").allowedOrigins("*").allowCredentials(true);}@Overridepublic void addInterceptors(InterceptorRegistry registry) {//排除拦截 除了登陆注册接口，其它都拦截//静态资源放行//注册拦截器 loginInterceptorregistry.addInterceptor(loginInterceptor)//添加拦截模式.addPathPatterns("/**")//放行的路径.excludePathPatterns("/login").excludePathPatterns("/static/**")//Swagger2 这里用"/v2/**"  Swagger3 这里用"/v3/**".excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v3/**", "/swagger-ui.html/**");WebMvcConfigurer.super.addInterceptors(registry);}/*** 配置静态资源访问拦截*/@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {//将所有/static/** 访问都映射到classpath:/static/目录下registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");WebMvcConfigurer.super.addResourceHandlers(registry);}
}