Spring Boot2篇 - 十一、Spring Boot 集成Swagger

灰太狼 2023-10-03 08:47 7阅读 0赞

十一、Spring Boot 集成Swagger

11.1 Swagger简介

前后端分离

  • 前端 -> 前端控制层、视图层
  • 后端 -> 后端控制层、服务层、数据访问层
  • 前后端通过API进行交互
  • 前后端相对独立且松耦合

产生的问题

  • 前后端集成,前端或者后端无法做到“及时协商,尽早解决”,最终导致问题集中爆发

解决方案

  • 首先定义schema [ 计划的提纲 ],并实时跟踪最新的API,降低集成风险

Swagger

  • 号称世界上最流行的API框架
  • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
  • 直接运行,在线测试API
  • 支持多种语言 (如:Java,PHP等)
  • 官网:https://swagger.io/

11.2 SpringBoot集成Swagger

  • 新建一个SpringBoot-web项目
  • 添加Maven依赖


    io.springfox
    springfox-swagger2
    2.9.2



    io.springfox
    springfox-swagger-ui
    2.9.2
  • 编写HelloController,测试确保运行成功

  • 要使用Swagger,我们需要编写一个配置类SwaggerConfig来配置 Swagger

    /**

    • @author cVzhanshi
    • @create 2021-06-21 14:16
      */
      @Configuration
      @EnableSwagger2 //开启Swagger2
      public class SwaggerConfig {

    }

  • 访问测试 :http://localhost:8080/swagger-ui.html ,可以看到swagger的界面
    在这里插入图片描述

  • 说明初步集成成功!

11.3 配置Swagger

  • Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {

    return new Docket(DocumentationType.SWAGGER_2);
    }

  • 通过apiInfo()属性配置文档信息

    //配置Swagger的Docket的bean实例
    private ApiInfo apiInfo(){

    1. //作者信息
    2. Contact contact = new Contact("cvzhanshi", "https://blog.csdn.net/qq_45408390?spm=1011.2124.3001.5343", "cvzhanshi@qq.com");
    3. ApiInfo apiInfo = new ApiInfo(
    4. "cVzhanshi的SwaggerApi文档",
    5. "It's now!",
    6. "v1.0",
    7. "https://blog.csdn.net/qq_45408390?spm=1011.2124.3001.5343",
    8. contact,
    9. "Apache 2.0",
    10. "http://www.apache.org/licenses/LICENSE-2.0",
    11. new ArrayList<VendorExtension>());
    12. return apiInfo;

    }

  • Docket 实例关联上 apiInfo()

    @Bean
    public Docket docket() {

    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

  • 重启项目,访问测试 http://localhost:8080/swagger-ui.html 看下效果
    在这里插入图片描述

11.4 配置扫描接口

  • 构建Docket时通过select()方法配置如何扫描接口

    @Bean
    public Docket getDocket(){

    1. return new Docket(DocumentationType.SWAGGER_2)
    2. .apiInfo(apiInfo())
    3. .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
    4. .apis(RequestHandlerSelectors.basePackage("cn.cvzhanshi.swagger.controller"))
    5. .build();

    }

  • 重启项目测试,由于我们配置根据包的路径扫描接口,所以我们只能看到一个类

  • 除了通过包路径配置扫描接口外,还可以通过配置其他方式扫描接口

    any() // 扫描所有,项目中的所有接口都会被扫描到
    none() // 不扫描接口
    // 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
    withMethodAnnotation(final Class<? extends Annotation> annotation)
    // 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
    withClassAnnotation(final Class<? extends Annotation> annotation)
    basePackage(final String basePackage) // 根据包路径扫描接口

  • 除此之外,我们还可以配置接口扫描过滤

    @Bean
    public Docket docket() {

    return new Docket(DocumentationType.SWAGGER_2)

    1. .apiInfo(apiInfo())
    2. .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
    3. .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
    4. // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
    5. .paths(PathSelectors.ant("/cvzhanshi/**"))
    6. .build();

    }

  • 可选值还有

    any() // 任何请求都扫描
    none() // 任何请求都不扫描
    regex(final String pathRegex) // 通过正则表达式控制
    ant(final String antPattern) // 通过ant()控制

在这里插入图片描述

11.5 配置Swagger开关

  • 通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了

    @Bean
    public Docket getDocket(){

    1. return new Docket(DocumentationType.SWAGGER_2)
    2. .apiInfo(apiInfo())
    3. .enable(false)
    4. .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
    5. .apis(RequestHandlerSelectors.basePackage("cn.cvzhanshi.swagger.controller"))
    6. .build();

    }

在这里插入图片描述

  • 如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?

    @Bean
    public Docket docket(Environment environment) {

    1. // 设置要显示swagger的环境
    2. Profiles of = Profiles.of("dev", "test");
    3. // 判断当前是否处于该环境
    4. // 通过 enable() 接收此参数判断是否要显示
    5. boolean b = environment.acceptsProfiles(of);
    6. return new Docket(DocumentationType.SWAGGER_2)
    7. .apiInfo(apiInfo())
    8. .enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
    9. .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
    10. .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
    11. // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
    12. .paths(PathSelectors.ant("/kuang/**"))
    13. .build();

    }

  • 测试动态配置Swagger

application-dev.properties

  1. server.port=8082

application-prod.properties

  1. server.port=8081

application.properties

  1. spring.profiles.active=prod

在这里插入图片描述

application.properties

  1. spring.profiles.active=dev

在这里插入图片描述

11.6 配置API分组

  • 如果没有配置分组,默认是default。通过groupName()方法即可配置分组

    @Bean
    public Docket getDocket(Environment environment){

    1. // 设置要显示swagger的环境
    2. Profiles of = Profiles.of("dev", "test");
    3. // 判断当前是否处于该环境
    4. // 通过 enable() 接收此参数判断是否要显示
    5. boolean flag = environment.acceptsProfiles(of);
    6. return new Docket(DocumentationType.SWAGGER_2)
    7. .apiInfo(apiInfo())
    8. .groupName("cvzhanshi")
    9. ...;

    }

  • 启动项目查看
    在这里插入图片描述

  • 如何配置多个分组?配置多个分组只需要配置多个docket即可

    @Bean
    public Docket docket1(){

    return new Docket(DocumentationType.SWAGGER_2).groupName(“group1”);
    }
    @Bean
    public Docket docket2(){

    return new Docket(DocumentationType.SWAGGER_2).groupName(“group2”);
    }
    @Bean
    public Docket docket3(){

    return new Docket(DocumentationType.SWAGGER_2).groupName(“group3”);
    }

在这里插入图片描述

设置了分组就能不同的人开发生成不同的api文档

11.7 实体配置

  • 新建一个实体类

    @ApiModel(“用户实体”)
    public class User {

    1. @ApiModelProperty("用户名")
    2. public String username;
    3. @ApiModelProperty("密码")
    4. public String password;

    }

  • 只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中

    @RequestMapping(“/getUser”)
    public User getUser(){

    return new User();
    }

在这里插入图片描述

注:并不是因为@ApiModel这个注解让实体显示在这里了,而是只要出现在接口方法的返回值上的实体都会显示在这里,而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

11.8 常用注解

Swagger的所有注解定义在io.swagger.annotations包下






























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

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

总结:
1.我们可以通过Swagger给一些比较难理解的属性或者接口, 增加注释信息
2.接口文档实时更新
3.可以在线测试

发表评论

表情:
评论列表 (有 0 条评论,7人围观)

还没有评论,来说两句吧...

相关阅读

    相关 Spring Boot 集成Swagger

    Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法