Spring Boot--06--整合Swagger

提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档

文章目录

Swagger
- 一、简介
- - - 官网：https://swagger.io/
- [Swagger 的优势](#Swagger 的优势)
二、基本使用
- [1. 导入相关依赖](#1. 导入相关依赖)
- [2. 编写配置文件](#2. 编写配置文件)
- - [2.1 配置基本信息](#2.1 配置基本信息)
  - [2.2 配置接口信息](#2.2 配置接口信息)
  - [2.3 配置分组信息](#2.3 配置分组信息)
- [3. 控制 Swagger 的开启](#3. 控制 Swagger 的开启)
- [4. 常用注解使用](#4. 常用注解使用)
- [5. 接口调用](#5. 接口调用)
- 6.请求头

Swagger

一、简介

官网：https://swagger.io/

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger消除了调用服务时可能会有的猜测。

Swagger 的优势

支持 API 自动生成同步的在线文档：使用 Swagger后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

二、基本使用

1. 导入相关依赖

通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。

xml 复制代码

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-web</artifactId>
            <version>2.9.2</version>
        </dependency>
        <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>

2. 编写配置文件

在配置文件 config 目录下，添加 swagger 的配置文件 SwaggerConfig.java

java 复制代码

@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
}

可以看到 Swagger 文档中大概有这四类信息

组
基本信息
接口信息
实体类信息

2.1 配置基本信息

SwaggerConfig.java 配置文件添加以下内容：

java 复制代码

    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置基本信息
                .apiInfo(apiInfo())
                ;
    }

    // 基本信息设置
    private ApiInfo apiInfo() {
        Contact contact = new Contact(
                "米大傻", // 作者姓名
                "https://blog.csdn.net/xhmico?type=blog", // 作者网址
                "777777777@163.com"); // 作者邮箱
        return new ApiInfoBuilder()
                .title("多加辣-接口文档") // 标题
                .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述
                .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
                .version("1.0") // 版本
                .license("Swagger-的使用(详细教程)")
                .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535")
                .contact(contact)
                .build();
    }

2.2 配置接口信息

java 复制代码

    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)

                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        //.any() // 扫描全部的接口，默认
                        //.none() // 全部不扫描
                        .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口

                )
                .paths(PathSelectors
                        .any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                )
                .build();
    }

2.3 配置分组信息

java 复制代码

    /**
     * 展示 controller 包下所有的接口
     */
    @Bean
    public Docket docket1() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("mike") // 修改组名为 "mike"
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
                )
                .paths(PathSelectors
                         .any() // 满足条件的路径，该断言总为true
                )
                .build();
    }

    /**
     * 展示路径为 /error 的所有接口（基础接口）
     */
    @Bean
    public Docket docket2() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("yank") // 修改组名为 "yank"
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        .any() // 扫描全部的接口，默认
                )
                .paths(PathSelectors
                        .ant("/error") // 满足字符串表达式路径
                )
                .build();
    }

3. 控制 Swagger 的开启

application.yml 内容如下，用于指定选择的环境：

yaml 复制代码

spring:
  profiles:
    active: dev

可以通过代码判断此时是在什么环境：dev、test、pro，如果是在 pro 生产环境，则关闭 swagger。

java 复制代码

    /**
     * swagger 配置
     * @param environment 环境
     */
    @Bean
    public Docket docket(Environment environment) {

        // 设置环境范围
        Profiles profiles = Profiles.of("dev","test");
        // 如果在该环境返回内则返回：true，反之返回 false
        boolean flag = environment.acceptsProfiles(profiles);

        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(flag) // 是否开启 swagger：true -> 开启，false -> 关闭
                ;
    }

4. 常用注解使用

@ApiModel

@ApiModelProperty

@ApiOperation

@ApiParam

案例

java 复制代码

@Data
@ApiModel(value = "获取用户列表DTO")
public class UserListReqDTO extends PageQuery {
    /**
     * 部门ID、前端传递 应要求 查询负责部门
     */
    @ApiModelProperty(value = "部门ID")
    private Long organizeId;

    /**
     * 姓名
     */
    @ApiModelProperty(value = "姓名")
    private String userName;

    /**
     * 角色ID
     */
    @ApiModelProperty(value = "角色ID")
    private Long roleId;

    /**
     * 部门层级
     */
    @ApiModelProperty(value = "部门层级")
    private Integer tagCode;
}

java 复制代码

@Slf4j
@Validated
@RestController
@RequestMapping("/download-task")
@Api(value = "下载中心", tags="release_2412")
public class DownloadTaskController {

    private final DownloadTaskService downloadTaskService;
    private final DownloadManager downloadManager;
    private final UserService userService;

    public DownloadTaskController(DownloadTaskService downloadTaskService, DownloadManager downloadManager, UserService userService) {
        this.downloadTaskService = downloadTaskService;
        this.downloadManager = downloadManager;
        this.userService = userService;
    }

    /**
     * 下载中心新增任务
     *
     * @param reqDTO
     */
    @PostMapping("/save")
    @ApiOperation(value = "新增任务", notes = "保存下载任务，状态为下载中")
    public ApiResponse save(@RequestBody @Validated @ApiParam("下载任务实体") DownloadTaskReqDTO reqDTO) {
        downloadTaskService.addDownloadTask(reqDTO);
        return ApiResponse.createBySuccess();
    }

    @PostMapping("/submit")
    @ApiOperation(value = "提交审核", notes = "提交导出任务审核", tags = {"2502"})
    public ApiResponse<Long> submit(@RequestBody @Validated @ApiParam("提交审核实体") DownloadTaskReqDTO reqDTO) {
        return ApiResponse.createBySuccess(downloadTaskService.submit(reqDTO));
    }


}

5. 接口调用

6.请求头

有时候我们的接口是需要获取请求头信息的，这样的话就还需要在 swagger 配置中添加请求头的配置。

java 复制代码

    @Bean
    public Docket docket() {
        // 设置请求头
        List<Parameter> parameters = new ArrayList<>();
        parameters.add(new ParameterBuilder()
                .name("token") // 字段名
                .description("token") // 描述
                .modelRef(new ModelRef("string")) // 数据类型
                .parameterType("header") // 参数类型
                .defaultValue("default value") // 默认值：可自己设置
                .hidden(true) // 是否隐藏
                .required(false) // 是否必须
                .build());

        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("mike") // 修改组名为 "mike"
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
                )
                .paths(PathSelectors
                        .any() // 满足条件的路径，该断言总为true
                )
                .build()

                // 添加请求头参数
                .globalOperationParameters(parameters);
    }

比如接口：

java 复制代码

    @GetMapping(value = "/get-token")
    @ApiOperation(value = "获取请求头中的token信息")
    public void getToken(
            @RequestHeader(value = "token",required = false) String token
    ) {
        // 直接获取 token 信息
        System.out.println("token = " + token);

        // 通过代码获取
        ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        if (servletRequestAttributes != null) {
            HttpServletRequest request = servletRequestAttributes.getRequest();
            String header = request.getHeader("token");
            System.err.println("header = " + header);
        }
    }