SpringBoot整合swagger

一、整合

1、版本

Spring Boot 2.6.x以下版本

比如下面版本组合是兼容的

Spring Boot版本	Swagger 版本
2.5.6	2.9.2

Spring Boot 2.6.x以上

Spring Boot版本	Swagger 版本
2.6.5	3.0.0

2、引入依赖

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

3、yaml文件添加配置

spring:
  application:
    name: rbac

  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4、开启Swagger

在SpringBoot的启动类 添加@EnableOpenApi注解，开启Swagger支持

@SpringBootApplication
@EnableOpenApi
public class RbacApplication {
    public static void main(String[] args) {
        SpringApplication.run(RbacApplication.class, args);
    }
}

5、启动服务器，访问swagger-ui,查看接口文档

http://localhost:9000/swagger-ui/

二、Swagger常用配置注解

1、@Api

用于请求的类上，表示对类的说明

• tags=“说明该类的作用，可以在ui界面上看到的注解”

• value=“在UI界面上看不到，所以不需要配置”

2、@ApiOperation

用在请求的方法上，说明方法的用途、作用

• value=“说明方法的用途、作用”

• notes=“方法的备注说明”

@ApiOperation(value = "说明方法的用途、作用",notes = "方法的备注说明")
    @GetMapping("/{id}")
    public Result queryByid(@PathVariable Long id) {

3、@ApiImplicitParams

用在请求的方法上，表示一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

• name：参数名

• value：参数的汉字说明、解释

• required：参数是否必须传

• paramType：参数放在哪个地方

  • header --> 请求参数的获取：@RequestHeader

  • query --> 请求参数的获取：@RequestParam

• path（用于restful接口）–> 请求参数的获取：@PathVariable

• dataType：参数类型，默认String，其它值dataType=“Integer”

• div（不常用）

• form（不常用）

• defaultValue：参数的默认值

   @GetMapping("all")
    @ApiOperation(value = "条件查询",notes ="可以根据用户姓名，注册时间等查询" )
    @ApiImplicitParams({
            @ApiImplicitParam(name = "realName",value = "用户名",required = false,paramType = "query"),
            @ApiImplicitParam(name = "dateRange",value = "注册时间范围",required = false,paramType = "query"),
            @ApiImplicitParam(name = "currentPage",value = "当前页",required = true,paramType = "query",dataType = "Integer"),
            @ApiImplicitParam(name = "pageSize",value = "每页显示的条数",required = true,paramType = "query",dataType = "Integer"),
    })
    public Result getAll(@RequestParam(value = "realName", required = false) String realName,
                         @RequestParam(value = "dateRange", required = false) String[] dateRange,
                         @RequestParam(value = "currentPage", required = false) Integer currentPage,
                         @RequestParam(value = "pageSize", required = false) Integer pageSize) {}

4、@ApiResponses：

用在请求的方法上，表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

• code：数字，例如400

• message：信息，例如"请求参数没填好"

• response：抛出异常的类

 @ApiOperation(value = "说明方法的用途、作用",notes = "方法的备注说明")
    @ApiResponses({
            @ApiResponse(code = 401,message = "未认证"),
            @ApiResponse(code = 403,message = "无权访问"),
            @ApiResponse(code = 404,message = "未找到")
    })
    @GetMapping("/{id}")
    public Result queryByid(@PathVariable Long id) {}

5、@ApiModel

用于响应类上，表示一个返回响应数据的信息

这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候

@ApiModel 用类上，描述类信息

@ApiModelProperty：用在属性上，描述响应类的属

@ApiModel("用户类")
public class SysUser implements Serializable {
  
    @ApiModelProperty("用户id")
    private Integer id;
 
    @ApiModelProperty("用户密码")
    private String password;

    @ApiModelProperty("用户电话")
    private String telephone;

    @ApiModelProperty("用户名")
    private String realname;

    @ApiModelProperty("出生年月")
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    @JsonFormat(pattern = "yyyy-MM-dd")
    private Date birthday;

    @ApiModelProperty("头像")
    private String headimg;

    @ApiModelProperty("是否可用")
    private Integer available;


    private Integer did;
    private String begin;
    private String end;
    private int pageSize;
    private int startPage;

    private static final long serialVersionUID = 1L;
}

 三、API信息配置

自定义配置类Swagger3Config

package com.wn.rbac.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
                .groupName("开发组001")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wn.rbac.controller"))  // 指定扫描的包  常用方式
                .build()
                .apiInfo(createApiInfo());
    }

    @Bean
    public ApiInfo createApiInfo() {
        return new ApiInfo(
                "Api Documentation",  //标题
                "XX项目Api文档",//描述
                "3.0",             //版本
                "https://www.kszs.xyz",//团队链接
                new Contact("fengSir", "https://www.kszs.xyz", "151303131@qq.com"),
                "Apache 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

四、Docket开关|过滤|分组 配置详解

1、开关设置 enable

开发环境才会用到swagger；正式环境需要关闭swagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
                .groupName("开发组001")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wn.rbac.controller"))  // 指定扫描的包  常用方式
                .build()
                .enable(false)
                .apiInfo(createApiInfo());
    }

2、设置过滤

apis (必选有调用select) 参数：

• any 所有都有效

• none都无效

• withClassAnnotation 根据类注解

• withMethodAnnotation 根据方法注解

• basePackage根据包路径（主要）

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
  /*其它省略先*/
  .select()
  .apis(RequestHandlerSelectors.basePackage("org.example.controller"))  
  .apiInfo(createApiInfo());
}

最后都要加build方法:

RequestHandlerSelectors.withClassAnnotation(Api.class)

RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)

3、设置分组

.groupName("开发组001")