一文搞懂Swagger,让你明白用了Swagger的好处!!!

原创

框架师

修改于 2020-06-11 17:31:49

5.3K0

修改于 2020-06-11 17:31:49

文章被收录于专栏：墨白的Java基地墨白的Java基地墨白的Java基地

前后端分离缺陷

了解Swagger之前,需要先知道什么是前后端分离

现在的时代
- SpringBoot + VUE..........等等
以前的时代
- SSM + JSP模板引擎====>后端程序员
前后端分离时代
- 后端:后端控制层 + 服务层 + 数据访问层
- 前端:前端控制层 + 视图层
  - 伪造后端交互数据,json数据已经存在,不需要后端传入json数据了,前端工程已经可以运行
- 前后端如何交互?
  - 通过相关的API接口进行交互
  - 前后端相对独立,松耦合
  - 前后端可以分别部署在不同的服务器上
但这样会产生新问题
- 前后端集成联调,前端和后端开发人员无法做到及时协商,尽早解决问题,就会导致项目延期
解决方案:
- 首先指定schema[计划大纲],团队实时更新最新的API,可以降低集成的风险;
- 早些年:指定world计划文档
- 前后端分离:
  - 前端测试后端:postMan
  - 后端提供接口,需要实时更新最新的消息和改动

Swagger简介

Swagger官网

号称世界上最流行的API框架
RestFul API文档在线生成工具--->>>API文档与API同步更新
可以直接运行,可以在线测试API接口
支持多种语言:(Java,PHP.....)

使用SpringBoot集成Swagger

创建SpringBoot-Web项目,导入相关依赖

注意事项:

在项目中使用Swagger需要SpringBox
swagger2
swaggerui

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

创建hello程序

扩展,一个hello程序有两个请求,一个是SpringBoot项目默认的/error

 @RestController
 public class HelloController {
     /**
      * 测试Controller
      *
      * @return
      */
     @GetMapping("/hello")
     public String hello() {
         return "你好呀!!!Swagger";
     }
 }

配置Swagger,新建SwaggerConfig

 @Configuration // 标识配置类
 @EnableSwagger2 // 开启Swagger
 public class SwaggerConfig {
     
 }

测试运行

唯一地址:http://localhost:8080/swagger-ui.html

配置Swagger信息

修改SwaagerConfig

 package com.mobai.swagger.config;
 
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.service.Contact;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
 import java.util.ArrayList;
 
 /**
  * Software：IntelliJ IDEA 2020.1 x64
  * Author: MoBai·杰
  * Date: 2020/6/11 13:33
  * ClassName:SwaggerConfig
  * 类描述： Swagger配置类
  */
 @Configuration // 标识配置类
 @EnableSwagger2 // 开启Swagger
 public class SwaggerConfig {
 
     /**
      * 配置了Swagger的Docket的Bean实例
      *
      * @return
      */
     @Bean
     public Docket docket() {
         return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
     }
 
     /**
      * 配置Swagger信息
      *
      * @return
      */
     private ApiInfo apiInfo() {
         // 配置作者信息
         Contact contact = new Contact("墨白",
                 "https://www.mobaijun.com",
                 "mobaijun8@163.com");
         // 配置API文档标题
         return new ApiInfo("框架师Api",
                 // API文档描述
                 "Api Documentation",
                 // API版本号
                 "1.0",
                 // 配置URL(公司官网/blog地址)
                 "https://www.mobaijun.com",
                 // 作者信息
                 contact,
                 // 以下内容默认即可
                 "Apache 2.0",
                 "http://www.apache.org/licenses/LICENSE-2.0",
                 new ArrayList());
     }
 
 }

Swagger配置扫描接口

Docket.select();

在SawggerConfig配置类完善配置扫描接口的参数

  /**
   * 配置了Swagger的Docket的Bean实例
   *
   * @return
   */
  @Bean
  public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              // 配置扫描接口
              .select()
              /*
               *RequestHandlerSelectors,配置要扫描接口的方式
               * 参数说明:
               * basePackage:基于包扫描
               * class:基于类扫描
               * any():扫描全部
               * none():全部都不扫描
               * withMethodAnnotation:通过方法的注解扫描
               * // withMethodAnnotation(GetMapping.class))
               * withClassAnnotation:通过类的注解扫描
               */
              .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
              // .paths()过滤,不扫描哪些接口
              .paths(PathSelectors.any())
              .build();
  }

配置Swagger启动

 /**
  * 配置了Swagger的Docket的Bean实例
  *
  * @return
  */
 @Bean
 public Docket docket() {
     return new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo())
             // 配置Swagger是否启动,默认:true
             .enable(false)
             // 配置扫描接口
             .select()
             .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
             .paths(PathSelectors.any())
             .build();
 }

小测试:如果有一个需求,需要你判断在生成环境中使用,在发布的时候不使用

开发思路
- 先判断.enable()是不是等于false
- 注入Enable(flag)
实现,添加application-dev.properties生产环境配置和application-pro.properties发布环境配置
默认application.properties环境配置添加

 # 开启profiles.active监听,dev测试环境,pro发布环境
 spring.profiles.active=dev

生产环境修改端口号

 server.port=8081

发布环境修改端口号

 server.port=8082

SwaggerConfig配置类判断当前环境

 /**
  * 配置了Swagger的Docket的Bean实例
  *
  * @return
  */
 @Bean
 public Docket docket(Environment environment) {
     // 设置要显示的Swagger环境
     Profiles profiles = Profiles.of("dev", "test");
     // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
     boolean flag = environment.acceptsProfiles(profiles);
 
     return new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo())
             // 监听自己设置的环境
             .enable(flag)
             // 配置扫描接口
             .select()
             .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
             .paths(PathSelectors.any())
             .build();
 }

配置API文档的分组

配置多个组,添加.groupName()

    /**
      * 配置了Swagger的Docket的Bean实例
      *
      * @return
      */
     @Bean
     public Docket docket(Environment environment) {
         // 设置要显示的Swagger环境
         Profiles profiles = Profiles.of("dev", "test");
         // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
         boolean flag = environment.acceptsProfiles(profiles);
 
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 // 配置分组
                 .groupName("墨白小组")
                 // 监听自己设置的环境
                 .enable(flag)
                 // 配置扫描接口
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
                 .paths(PathSelectors.any())
                 .build();
 }

效果

配置多个组

 @Configuration // 标识配置类
 @EnableSwagger2 // 开启Swagger
 public class SwaggerConfig {
 
     /**
      * 添加A组
      * 每个组各司其职
      *
      * @return
      */
     @Bean
     public Docket docket1() {
         return new Docket(DocumentationType.SWAGGER_2)
                 .groupName("A");
     }
 
     /**
      * 添加B组
      *
      * @return
      */
     @Bean
     public Docket docket2() {
         return new Docket(DocumentationType.SWAGGER_2)
                 .groupName("B");
     }
 
     /**
      * 添加C组
      *
      * @return
      */
     @Bean
     public Docket docket3() {
         return new Docket(DocumentationType.SWAGGER_2)
                 .groupName("C");
     }
 
     /**
      * 配置了Swagger的Docket的Bean实例
      *
      * @return
      */
     @Bean
     public Docket docket(Environment environment) {
         // 设置要显示的Swagger环境
         Profiles profiles = Profiles.of("dev", "test");
         // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
         boolean flag = environment.acceptsProfiles(profiles);
 
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 // 配置分组
                 .groupName("墨白小组")
                 // 监听自己设置的环境
                 .enable(flag)
                 // 配置扫描接口
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
                 .paths(PathSelectors.any())
                 .build();
     }

效果

实体类配置

 @ApiModel("用户实体类") // 添加注释
 public class User {
     // 添加注释
     @ApiModelProperty("年龄")
     private Integer age;
 
     @ApiModelProperty("姓名")
     private String name;
 
     @ApiModelProperty("账号")
     private String username;
 
     @ApiModelProperty("密码")
     private String password;
 
     public Integer getAge() {
         return age;
     }
 
     public void setAge(Integer age) {
         this.age = age;
     }
 
     public String getName() {
         return name;
     }
 
     public void setName(String name) {
         this.name = name;
     }
 
     public String getUsername() {
         return username;
     }
 
     public void setUsername(String username) {
         this.username = username;
     }
 
     public String getPassword() {
         return password;
     }
 
     public void setPassword(String password) {
         this.password = password;
     }
 }

效果

Swagger常用注解
- @ApiModel("注释"):实体类添加注释
- @ApiModelProperty("注释"):给实体类属性添加注释
- @ApiOperation("注释")给接口(Controller)方法添加注释,放在方法上
- @ApiParam("")给方法的参数添加注释
- @Api("")给类添加注释
controller

 package com.mobai.swagger.controller;
 
 import com.mobai.swagger.pojo.User;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiParam;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 /**
  * Software：IntelliJ IDEA 2020.1 x64
  * Author: MoBai·杰
  * Date: 2020/6/11 13:25
  * ClassName:HelloController
  * 类描述： 测试类
  */
 @ApiOperation("")
 @RestController
 public class HelloController {
     /**
      * 测试Controller
      *
      * @return
      */
     @GetMapping("/hello")
     public String hello() {
         return "不喜欢你啦你好呀!!!Swagger";
     }
 
     /**
      * 只要我们的接口中,返回值存在实体类,Swagger就会扫描到
      *
      * @return
      */
     @PostMapping("/user")
     public User user() {
         return new User();
     }
 
     @ApiOperation("Post测试类")
     @PostMapping(value = "/post")
     public User post(@ApiParam("用户对象") User user) {
         return user;
     }
 }

总结
- 创建SpringBoot项目,导入Swagger依赖
  - Swagger2
  - Swagger-ui
- 创建Swagger配置类
  - 添加@Configuration注解,标识配置类
  - 添加@EnableSwagger2注解开启Swagger
- 配置Swagger的Docket的Bean实例
- 配置Swagger信息