2023-1-29 SpringBoot下Swagger2快速入门和配置使用（docket）

雪饼熊

已于 2023-07-28 15:34:25 修改

阅读量1k

点赞数 2

分类专栏：计算机系统-高级编程语言-Java 文章标签： java 开发语言 spring boot

于 2023-04-01 10:18:15 首次发布

本文链接：https://blog.csdn.net/qq_45507768/article/details/129893379

版权

计算机系统-高级编程语言-Java 专栏收录该内容

11 篇文章 1 订阅

订阅专栏

SpringBoot下Swagger快速入门使用

文章目录

SpringBoot下Swagger快速入门使用

@[toc]
1、swagger初识
2、Swagger快速开始
3、Swagger的使用配置
4、swagger注释注解

1、swagger初识

1、前导知识
- 前后端开发阶段：
  - 大后端时代：前端设计静态页面，后端使用模板引擎实现动态展示；主要开发点在后端代码上。
  - 前后端分离：
    
    前端：前端不再需要后端代码即可运行部署；其开发分为：前端控制层、视图层。
    
    后端：后端控制层、服务层、数据访问层。
- 前后端开发联调问题：
  - 前端人员和后端人员无法实时协商，尽快解决（比如前端后续更新，添加了新功能展示，需要通知后端人员提供新的接口），开发难度变大。
- 解决方案
  - 制定计划大纲，及时更新最新api。
    - 早期：使用word文档完成。
    - 中期：使用各种接口测试工具
      - 例如：前端使用postman测试，后端提供最新接口。
  - 使用swagger
2、Swagger 官网：API Documentation & Design Tools for Teams | Swagger
- 定义： 是一个api框架，RestFul api 文档在线生成工具。利用代码在线生成接口说明文档，且可以在线测试。
- 好处：
  - 后端：
    - 不用再手写WiKi接口拼大量的参数，避免手写错误
    - 对代码侵入性低，采用全注解的方式，开发简单
    - 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
    - 缺点：增加了开发成本，写接口还得再写一套参数配置
  - 前端：
    - 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
    - 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题
  - 测试：
    - 对于某些没有前端界面UI的功能，可以用它来测试接口
    - 操作简单，不用了解具体代码就可以操作
    - 操作简单，不用了解具体代码就可以操作
  - 支持java、php等语言。

2、Swagger快速开始

1、使用三步走

1）导入依赖

<!-- ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

2）配置：默认配置。

@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用默认配置
}

3）使用

访问：http://localhost:8080/swagger-ui.html

3、Swagger的使用配置

1、使用swagger的实例docket配置基础信息

@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用自定义配置
    
    //使用docket实例用于取代swagger原本的配置。
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	.groupName("grp1")//设置分组
            	.enable(true)
            	.select()
          	.apis(RequestHandlerSelectors.basePackage("com.zm.controller"))
            	.paths(PathSelectors.any())
            	.build();
    }
    
    private ApiInfo apiInfo() {
        
        Contact DEFAULT_CONTACT = new Contact("作者名:zm", "指定的某个url", "作者email");
        
        return new ApiInfo("标题：我的Swagger-Api文档", 
                           "本文档描述信息", "版本：1.0", 
                           "项目组织网址（一个url）", 
                           DEFAULT_CONTACT, 
                           "Apache 2.0", 
                           "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

Docket对象说明：

1）构造方法：需要一个DocumentationType类对象，这里选择SWAGGER_2

在这里插入图片描述

2）apiInfo()：用于配置swagger 信息。

这个类对象仅有如下属性，且只有一个构造方法。

在这里插入图片描述

官方提供了一个默认对象的构造方法，在该类的静态代码块中。

我们可以参照其创建一个apiInfo实例。

3）apiInfo中的contact对象：用于配置作者信息。

同样的，再ApiInfo类中同样提供了Contac类对象的构造。

在这里插入图片描述

2、使用swagger的实例docket配置扫描接口

用法：使用docket对象的select()进行构造配置。
```
@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用自定义配置
    
    //使用docket实例用于取代swagger原本的配置。
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                ......
            	.select()
          	.apis(RequestHandlerSelectors.basePackage("com.zm.controller"))
            	.paths(PathSelectors.any())
            	.build();
    }
    
    private ApiInfo apiInfo() {
     ......
    }
}
```
- 1）select().xxx（链式构造）.build()：
  
  这里select方法执行使用了建造者模式，最后使用build方法返回Docket对象。
  
  这里select()返回对象可进行两步构造
  - 1）apis()：用于配置要扫描接口的方式，其接受参数是一个函数式接口：Predicate selector。
    
    这里使用RequestHandlerSelectors.basePackage配置为扫描包：
  - 2）paths()：用于配置过滤路径，其接受参数是一个函数式接口：Predicate selector。
    
    这里使用PathSelectors.ant(“/book/**”)，表示筛选com.zm.controller包下访问接口为/book/下的接口。

3、使用swagger的实例docket配置的启动与关闭

......
public class SwaggerConfiguration {//使用自定义配置
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                ......
            	.enable(true)
            	.select()
          		......
            	.build();
    }
    
    private ApiInfo apiInfo() {
       ......
    }
}

使用enable(boolean)：默认为true代表配置有效，可修改为false。

在这里插入图片描述

实际作用：在生产和发布的不同环境下，希望swagger在生产环境中生效，发布环境中无效。

1）判断当前使用环境

2）读取配置

这里提供两种方法：

//1、
@Bean
    public Docket createRestApi(Environment env) {
        //显示swagger环境
        Profiles profiles = Profiles.of("dev");
        //判断当前环境
        boolean flag = env.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.enable(flag)
                .apis(RequestHandlerSelectors.basePackage("com.wz.controller"))
                .paths(PathSelectors.any())
                .build();
    }

//2、
@Value("${spring.profiles.active}")
private String activated;
 @Bean
    public Docket createRestApi(Environment env) {
        //判断当前环境
        boolean flag = activated.equals("dev") ? true : false;

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wz.controller"))
                .paths(PathSelectors.any())
                .build();
    }

4、使用swagger的实例docket配置的分组

@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用自定义配置
    
    //使用docket实例用于取代swagger原本的配置。
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                ......
            	.groupName("grp1")//设置分组
            	.select()
				......
            	.build();
    }
    
    private ApiInfo apiInfo() {
     ......
    }
}

groupName(“grp1”)：用于设置分组,同一配置类下可以有多个docket，每个docket拥有一个组。

4、swagger注释注解

@ApiModel(“xxx”)：给控制层返回的实体类对象添加注释
@ApiModelProperty(“xxx”)：给字段添加注释
@Api(“xxx”)：作用在控制层类上
@ApiOperation(“xxx”)：作用于方法添加注释
@ApiParam(“xxx”)：作用于控制层接口参数添加注释

雪饼熊

关注

2
点赞
踩
4

收藏

觉得还不错? 一键收藏
0
评论
2023-1-29 SpringBoot下Swagger2快速入门和配置使用（docket）

这里使用PathSelectors.ant(“/book/**”)，表示筛选com.zm.controller包下访问接口为/book/下的接口。**定义：**是一个api框架，RestFul api 文档在线生成工具。1）apis()：用于配置要扫描接口的方式，其接受参数是一个函数式接口：Predicate selector。2）paths()：用于配置过滤路径，其接受参数是一个函数式接口：Predicate selector。用法：使用docket对象的select()进行构造配置。
复制链接

扫一扫