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

小人物大Dream

已于 2022-09-01 21:56:10 修改

阅读量2.2k

点赞数 2

分类专栏： Java语言学习文章标签： spring boot 学习 java

于 2022-08-23 14:05:09 首次发布

本文链接：https://blog.csdn.net/weixin_45762767/article/details/126483106

版权

Java语言学习专栏收录该内容

17 篇文章 0 订阅

订阅专栏

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实例
    @Bean
    public 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信息 apiInfo
    private 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：数字，例如400
        message：信息，例如"请求参数没填好"
        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
    @Autowired
    private  LoginInterceptor  loginInterceptor;

    /**
     * 解决跨域问题
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
             registry.addMapping("/**")
                     .allowedHeaders("*")
                     .allowedMethods("*")
                     .allowedOrigins("*")
                     .allowCredentials(true);
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        //排除拦截 除了登陆注册接口，其它都拦截
        //静态资源放行
        //注册拦截器 loginInterceptor
        registry.addInterceptor(loginInterceptor)
                //添加拦截模式
                .addPathPatterns("/**")
                //放行的路径
                .excludePathPatterns("/login")
                .excludePathPatterns("/static/**")
                //Swagger2 这里用"/v2/**"  Swagger3 这里用"/v3/**"
                .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v3/**", "/swagger-ui.html/**");
        WebMvcConfigurer.super.addInterceptors(registry);
    }

    /**
     * 配置静态资源访问拦截
     */
    @Override
    public 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);
    }
}