当前位置： 首页 > article >正文

Spring Boot--06--整合Swagger

article 2025/3/1 15:00:32

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

文章目录

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

Swagger

一、简介

官网：https://swagger.io/

在这里插入图片描述

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

Swagger 的优势

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

二、基本使用

1. 导入相关依赖

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

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

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

在这里插入图片描述
可以看到 Swagger 文档中大概有这四类信息

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

2.1 配置基本信息

在这里插入图片描述
SwaggerConfig.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 配置接口信息

在这里插入图片描述

    @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 配置分组信息

在这里插入图片描述

    /**
     * 展示 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 内容如下，用于指定选择的环境：

spring:
  profiles:
    active: dev

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

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

在这里插入图片描述
在这里插入图片描述

案例

@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;
}

@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 配置中添加请求头的配置。
    @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);
    }

比如接口：

    @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);
        }
    }

在这里插入图片描述


http://www.kler.cn/a/445802.html

相关文章：

  • 前端工程中.git文件夹内容分析
  • Flutter组件————AppBar
  • go语言zero框架中config读取不到.env文件问题排查与解决方案
  • 【日常笔记】Spring boot：编写 Content type = ‘text/plain‘ 接口
  • 【读书笔记】《论语别裁》学而有何乐
  • Git使用步骤
  • 【Vulkan入门】16-IndexBuffer
  • CPU性能优化-基于源代码的CPU调优
  • 安装指南｜OpenCSG Starship上架GitHub Marketplace
  • Hadoop实验：关于MapReduce词频统计的实验步骤
  • LSTM (Long Short-Term Memory)
  • MQTT客户端向服务端建立ssl连接报错
  • 期末复习-编译原理（手写笔记）
  • 脉冲计数 记录按下的次数
  • BGP的六种状态分别是什么？
  • ElementPlus Table 表格实现可编辑单元格
  • 高中数学刷题版：集合与函数概念-函数的概念[笔记总结-干货]
  • WatchAlert - 开源多数据源告警引擎
  • 10. 考勤信息
  • Vue.js前端框架教程1：Vue应用启动和Vue组件