Swagger笔记

一. 前后端分离

1. 说明

后端: 后端控制层, 服务层, 数据访问层

前端: 前端控制层, 视图层

​ 伪造数据, json. 不需要后端, 前端工程依旧可以跑起来

前后端如何交互 ==> API

前后端相互独立 ==> 松耦合

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

2. 产生一个问题:

前后端集成联调, 前端人员和后端人员无法做到"及时协商, 尽早解决"

3. 解决方案:

首先指定"Schema", 实时更新最新API, 降低集成的风险.

1. 早些年指定word文档
2. 前后端分离:
   1. 前端测试后端接口: postman
   2. 后端提供接口, 需要实时更新最新的消息及改动!

二. Swagger

1. 说明

1. 号称世界上最流行的Api框架
2. RestFul Api文档在线自动生成根据 ==> Api文档与Api定义同步更新
3. 直接运行, 可以在线测试API接口
4. 支持多种语言: Java, PHP

2. SpringBoot集成Swagger

1. 新建一个Springboot web项目

2. 导入依赖

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

3. 创建一个hello工程

4. 配置Swagger

   @Configuration
   @EnableSwagger2 //开启Swagger2
   public class SwaggerConfig {
   }
   

5. 测试, 访问swagger主页

   

3. 配置Swagger信息

1. Swagger配置类

   @Configuration
   @EnableSwagger2 //开启Swagger2
   public class SwaggerConfig {
       // 配置Swagger的Docket的bean实例
       @Bean
       public Docket docket(){
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo());
       }
   
       // 配置Swagger信息: apiInfo
       private ApiInfo apiInfo(){
           // 作者信息
           Contact contact = new Contact("jiang锋时刻", "http://www.jiangfengtime.top", "jiangfengtime@gmail.com");
           return new ApiInfo(
                   "Api 文档",
                   "描述信息",
                   "1.5",
                   "http://www.jiangfengtime.top",
                   contact,
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   new ArrayList());
       }
   }
   

   

4. Swagger配置扫描接口

1. 配置

   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           .enable(true)  //是否开启swagger
           .select()
           /**
            * RequestHandlerSelectors: 配置要扫描接口的方式
            *  basePackage: 扫描指定包下的方法
            *  any: 扫描全部
            *  none: 都不扫描
            *  withClassAnnotation: 扫描类上的注解, 参数是一个注解的反射对象
            *  withMethodAnnotation: 扫描方法上的注解
            *
            */
           .apis(RequestHandlerSelectors.basePackage("com.hjf.controller"))
           // .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
           // 只扫描hello下的
           .paths(PathSelectors.ant("/hello/**"))
           .build()
           ;
   }
   

2. 应用: 希望Swagger在生产环境中使用, 在开发的时候不使用.

   1.判断是否是生产环境 flag = xx
   2.注入enable(flag)

   @Bean
   public Docket docket(Environment env){
       // 设置要显示的Swagger环境
       Profiles profiles = Profiles.of("dev", "test");
       // 通过env.acceptsProfiles判断是否除了在自己设定的环境中
       boolean flag = env.acceptsProfiles(profiles);
       return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           .enable(flag)  //是否开启swagger
           .select()
           .apis(RequestHandlerSelectors.basePackage("com.hjf.controller"))
           .build();
   }
   

5. Swagger分组

1. 代码

   @Configuration
   @EnableSwagger2 //开启Swagger2
   public class SwaggerConfig {
   
       @Bean
       public Docket docketA(){
           return new Docket(DocumentationType.SWAGGER_2).groupName("分组A");
       }
       @Bean
       public Docket docketB(){
           return new Docket(DocumentationType.SWAGGER_2).groupName("分组B");
       }
       @Bean
       public Docket docketC(){
           return new Docket(DocumentationType.SWAGGER_2).groupName("分组C");
       }
   }
   

   

6. 实体类配置

1. 创建一个实体类

   @ApiModel("用户实体类")  // 给类加注释
   public class User {
       @ApiModelProperty("用户名")    // 给属性加注释
       public String username;
       @ApiModelProperty("密码")
       public String password;
   }
   
   

2. 创建一个返回值类型为User的controller

   // 只要我们的接口中, 返回值中存在实体类, 他就会被扫描到Swagger
   @PostMapping("/user")
   public User user(){
       return new User();
   }
   

3. 运行
   

7. 测试

1. 进入测试
   

2. 参数输入
   

3. 测试结果
   

8. 总结:

1. 我们可以通过Swagger给一些比较难理解的属性或接口, 增加注释信息
2. 接口文档实时更新
3. 可在线测试
4. 注意: 在项目正式发布时, 一定要关闭Swagger, 不能向外暴露API