Swagger简述以及集成SpringBoot。【狂神】

1. Swagger简介

后端时代 ：

• 前端只能管理静态页面；html==> 后端。模版引擎 JSP ==> 后端 是主力

前后端分离时代：

目前较为流行的框架是 Vue + SpringBoot

• 前端 -> 前端控制层、视图层
• 后端 -> 后端控制层、服务层、数据访问层
• 前后端通过API进行交互
• 前后端相对独立且松耦合
  • 伪造前端数据，json 没有后端前端也是可以跑起来的

前后端如何交互 ==> API

• 前后端相对独立 ，松耦合；

• 前后端甚至可以部署在不同的服务器上；

但是会产生一个问题 ：

• 前后端集合联调，前端人员和后端人员无法做到及时的沟通协商

解决方法：

• 首先制定schema【计划的提纲】 ， 实时的更新最新API，降低集成的风险
• 早些年：制定word计划文档；
• 前后端分离：
  • 前端测试后端接口；postman
  • 后端提供接口，需要实时更新最新的消息及改

于是为了解决这些文写问题就出现了我们的Swagger～～～

Swagger

• 号称世界上最流行的API框架；
• RestFul Api 文档在线自动生成工具=> Api文档与API定义同步更新
• 直接运行，可以在线测试APi接口；
• 支持多种语言（Java，ohp）

官方文档 ：
https://swagger.io/

SpringBoot集成swagger

1. 新建项目（springboot-web）

1.选择web依赖即可

2.导入相关依赖

在项目中使用Swagger 需要springfox，两个jar包；

• Springfox-swagger2

  <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 **Springfox-swagger2** -->
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>3.0.0</version>
  </dependency>
  
  

• springfox-swagger-ui

  <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
  <dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>3.0.0</version>
  </dependency>
  
  

3.编写HelloController 并测试是否成功

@RestController
public class HelloController {


    @RequestMapping("/hello")
    public String Hello(){
        return "hello";
    }
}

经测试么的问题

2.配置Swagger

@Configuration
@EnableSwagger2      //开启swagger2 注意是 222222！！！！
public class SwaggerConfig {

}

3. 测试运行：

这时候测试运行我发现出现了下面这个错误！！！

0S boot. Springapplication Application run failed

springboot跑不起来了

解决方法 ：在查阅了许多资料之后发现 我写的没问题。 是版本问题，将springboot降级到2.5.2 发现 成功了 。。。。。

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

可以看到swagger的界面；

配置Swagger

Swagger 的bean实例Docket

ps 。 看源码找方法比较快乐一些～～～～

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

@Configuration
@EnableSwagger2      //开启swagger2 注意是 222222！！！！
public class SwaggerConfig {

    //配置swagger的Docket 的 bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置swagger的配置信息 apiInfo
    private ApiInfo apiInfo() {


       String contact = "zhen";
        return new ApiInfo(
                "甄的Swagger日记",
                "嘿嘿嘿是我写的o",
                "1.0",
                "urn:tos",
                contact,
                "1111",
                "http://www.apache.org/licenses/LICENSE-2.0"
        );

    }
}

运行测试 发现seagger里的[页面换了 成功~~~

Swagger配置扫描接口

1、构建Docket时通过select()方法配置怎么扫描接口。

 //配置swagger的Docket 的 bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()           // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //RequestHandlerSelectors配置要扫描接口的方式
                //basePackage指定要扫描的包
                //ang 扫描任意包
                .apis(RequestHandlerSelectors.basePackage("com.zhen.controller"))
    }

2.还可以配置接口扫描过滤：

 //配置swagger的Docket 的 bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()           // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //RequestHandlerSelectors配置要扫描接口的方式
                //basePackage指定要扫描的包
                //ang 扫描任意包
                .apis(RequestHandlerSelectors.basePackage("com.zhen.controller"))
                //path 过滤路径
                .paths(PathSelectors.ant("/zhen/**"))
                .build();
    }

3.配置Swagger开关

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

    @Bean
      public Docket docket() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .enable(false)    //关闭
                  .select()           // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                  //RequestHandlerSelectors配置要扫描接口的方式
                  //basePackage指定要扫描的包
                  //ang 扫描任意包
                  .apis(RequestHandlerSelectors.basePackage("com.zhen.controller"))
                  //path 过滤路径
                  //.paths(PathSelectors.ant("/zhen/**"))
                  .build();
      }
  
  

  ​ 测试 ： 确实无法访问了

  

**我只希望我的Swagger在生产环境中使用，在发布时不使用**

• 判断是不是生产环境

• 再通过enable判断

   //配置swagger的Docket 的 bean实例
      @Bean
      public Docket docket(Environment environment) {
  
          // 设置要显示swagger的环境
          Profiles of = Profiles.of("dev", "test");
          // 判断当前是否处于该环境
          // 通过 enable() 接收此参数判断是否要显示
          boolean b = environment.acceptsProfiles(of);
          
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .enable(false)    //是否启用swagger
                  .select()           // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                  //RequestHandlerSelectors配置要扫描接口的方式
                  //basePackage指定要扫描的包
                  //ang 扫描任意包
                  .apis(RequestHandlerSelectors.basePackage("com.zhen.controller"))
                  //path 过滤路径
                  //.paths(PathSelectors.ant("/zhen/**"))
                  .build();
      }
  
  

配置Api文件分组

•                 .groupName("zhen")
  

• 一个docker能返回一个组 配置多个分组只需要配置多个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");
  }
  

实体类配置

• 新建实体类

  @ApiModel("用户实体")
  public class User {
      @ApiModelProperty("用户名")
      public String username;
      @ApiModelProperty("密码")
      public String password;
  }
  

• 编写controller

   @RequestMapping("/getUser")
      public User getUser(){
          return new User();
      }
  

  ps.

  • @ApiModel为类添加注释

  • @ApiModelProperty为类属性添加注释

• 常用注释

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

• 给请求的接口配置一些注释

   @ApiOperation("Zhen的接口")
      @PostMapping("/zhen")
      @ResponseBody
      public String zhen(@ApiParam("用户名 ： ")String username){
          return username;
      }
  

【注意点】

在正式发布的时候，记得关闭Swagger！！！ 为了安全和节省内存～～·