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

SpringBoot下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
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值