Spring Boot(十五)--------Swagger介绍及集成

Spring Boot(十五)--------Swagger介绍及集成

25、Swagger

25.1 前言

  • 前后端分离:Vue+SpringBoot
  • 后端时代:前端只需要管理静态页面:html、css、js。后端通过模板引擎JSP重写,后端是主力
25.1.1 前后端分离时代
  • 前端:前端控制层,视图层;伪造后端数据,json。不需要后端,前端功能仍旧能跑起来
  • 后端:后端控制层(Controller),服务层,数据访问层
  • 前后端通过API进行交互,前后端相对独立且松耦合
25.1.2 产生的问题
  • 强后端集成联调,前端或后端无法做到”及时协商,尽早解决“,最终导致问题集中爆发
25.1.3 解决方案
  • 首先定义提纲,并实时跟踪最新的API,降低集成风险
  • 早些年:指定word计划文档
  • 前后端分离
    • 前端测试后端接口:postman
    • 后端提供接口,需要实时更新最新的消息及改动

25.2 Swagger

25.3 SpringBoot集成Swagger

  • 导入springfox-swagger2springfox-swagger-ui的jar包
  • 使用Swagger时,需要使用jdk1.8+,否则swagger2无法运行
  • 新建一个SpringBoot项目,导入web依赖
  • 3.0版本之前
<!--2.9.2版本-->
<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>
  • 3.0版本之后,springboot版本2.5.6
<!--3.0.0版本-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
   <version>3.0.0</version>
</dependency>
  • 编写HelloController,测试是否运行成功
@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}
  • 应用主类增加注解@EnableOpenApi
@SpringBootApplication
@EnableOpenApi
public class SwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }

}
  • 测试访问网址:http://localhost:8080/swagger-ui/index.htmlhttp://localhost:8080/swagger-ui/,可以看到swagger页面

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Mg4c27ow-1646897175734)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220309173901627.png)]

25.4 配置Swagger

  • 新建一个SwaggerConfig类,并且加上注解@Configuration

  • Swagger的Bean实例是Docket,所以通过配置Docket实例来配置Swagger,可以通过apiInfo()属性配置文档信息

@Configuration
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo());
    }
    //配置Swagger信息apiInfo()
    private ApiInfo apiInfo(){
        return new ApiInfo(
                //标题
                "zmt的Swagger Api文档",
                //描述
                "作者描述",
                //版本
                "1.0",
                //服务条款url
                "https://www.baidu.com",
                //作者信息
                new Contact("zzz", "https://www.baidu.com", "123@qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

  • 重启项目,访问http://localhost:8080/swagger-ui/,看下效果

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-6D6NL22N-1646897175737)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220309210047430.png)]

25.5 配置扫描接口

  • 构建Docket时通过select()方法配置如何扫描接口
@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors 配置要扫描接口的方式
        //basePackage 指定要扫描的包
        .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
        //建造者模式
        .build();
}
  • 重启项目测试,发现只扫描了指定包下的接口

  • 除了通过包 路径配置扫描接口外,还可以通过配置其他方式扫描接口,这里注释一下所有的配置方式

// 根据包路径扫描接口
basePackage(final String basePackage) 
// 扫描所有,项目中的所有接口都会被扫描到    
any() 
// 不扫描    
none() 
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
  • 还可以配置接口扫描过滤
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){

    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors 配置要扫描接口的方式
        //basePackage 指定要扫描的包
        .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
        //过滤什么路径,只扫描以/zzz开头的接口路径
        .paths(PathSelectors.ant("/zzz/**"))
        //建造者模式
        .build();
}
  • 可选值有
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

25.6 配置Swagger开关

  • 通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器种访问
@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        //是否启用swagger
        .enable(false)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
        //.paths(PathSelectors.ant("/zzz/**"))
        .build();
}
  • 重启项目,可以看到无法浏览器访问swagger

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-kEkbcyUm-1646897175739)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310134920400.png)]

  • 如何动态配置,当项目处于dev测试环境时显示swagger,处于pro发布环境时不显示swagger
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){

    //找对包org.springframework.core.env.Profiles;
    //设置要显示的swagger环境
    Profiles profiles = Profiles.of("dev","test");
    //获取项目运行环境
    //通过environment.acceptsProfiles(profiles),判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        //实现动态配置swagger
        .enable(flag)
        .select()     .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
        //.paths(PathSelectors.ant("/zzz/**"))
        .build();
}
  • 可以在项目种增加配置文件
#dev测试环境
server.port=8081

#pro生产环境
server.port=8082

#配置哪个环境生效
spring.profiles.active=dev
  • 重启测试,启用dev配置文件时,可以访问swagger;启动pro配置文件时,不能访问swagger

25.7 配置API分组

  • 如果没有配置分组,默认是default。通过groupName()方法即可配置分组
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){
		...
            
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("zzz")
        ...
    }
  • 重启项目查看分组

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-KExmFtXH-1646897175740)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310145819418.png)]

  • SwaggerConfig中配置多个docket()方法就可以配置多个分组
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.OAS_30).groupName("group1");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.OAS_30).groupName("group2");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.OAS_30).groupName("group3");
}
  • 重启项目即可查看

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-RIC1QBRC-1646897175741)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310145959573.png)]

25.8 实体类配置

  • 新建一个实体类
public class User {
    public String username;
    public String password;
}
  • 只要这个实体在请求接口的返回值上,都能映射到实体项中
  • HelloController类中写user()方法
//只要接口返回值中存在实体类,该实体类就会被扫描到swagger中
@PostMapping(value = "/user")
public User user(){
    return new User();
}
  • 重启测试

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-6YbvolBD-1646897175741)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310150640894.png)]

  • 还可以给实体类加文档注释
//给实体类加文档注释
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}
  • 重启测试

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-tifzkCGn-1646897175743)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310150835077.png)]

  • 不是因为加了注解,才让实体类显示在swagger中,而是在接口方法的返回值上出现的实体类才会显示在swagger中。上面的注解只是为了实体类增加注释的
  • 也可以给接口配置一些注释
@RestController
public class HelloController {

    @ApiOperation("Hello控制接口")
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    //只要接口返回值中存在实体类,该实体类就会被扫描到swagger中
    @ApiOperation("User控制接口")
    @PostMapping(value = "/user")
    public User user(@ApiParam("用户") User user){
        return user;
    }
}
  • 重启测试

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-xGvmUV0K-1646897175744)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310151913901.png)]

25.9 常用注解

  • Swagger的所有注解定义在io.swagger.annotations包下
Swagger注解简单说明
@Api(tags = “xxx模块说明”)作用在模块类上
@ApiOperation(“xxx接口说明”)作用在接口方法上
@ApiModel(“xxxPOJO说明”)作用在模型类上:如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)作用在类方法和属性上,hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)作用在参数、方法和字段上,类似@ApiModelProperty

25.10 Swagger测试接口

  • swagger可以用来测试接口

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-hMek1OQt-1646897175748)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310152206611.png)]

  • 输入测试的用户名密码

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-KEOyRwE4-1646897175749)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310152241591.png)]

  • 会显示测试接口的结果

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-vlIHlEuW-1646897175749)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20220310152355626.png)]

25.11 小结

  • Swagger可以给一些比较难理解的属性或者接口,增加一些配置信息,让人更容易阅读

  • 接口文档实时更新,可以在线测试

  • 相较于传统的PostmanCurl方式测试接口,使用swagger是傻瓜式操作,不需要额外说明文档,不容易出错,只需要录入数据然后点击Execute,如果再配合自动化框架,可以说基本不需要人为操作

  • Swagger是个优秀的工具,现在国内已经有很多的中小型互联网公司都在使用它,相较于传统的要先出Word接口文档再测试的方式,显然这样也更符合现在的快速迭代开发行情。

  • 在正式环境要记得关闭Swagger,一来出于安全考虑二来也可以节省运行时的内存

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值