SpringBoot 集成Swagger

1. swagger简介

前后端分离时代：
前端 -> 前端控制层，前端视图层
后端 -> 后端控制层，服务处，数据接入层
前后端通过API进行交互，可以使得程序独立且松耦合

1. swagger是什么？

swagger是一款让你更好的书写API文档的规范且完整的框架，提供了描述生产，消费和可视化的RESTful 风格编程，是由庞大的工具集合支撑的形式化规范，这个集合涵盖了从终端用户接口，底层代码到商业的API管理层面！

2. 为什么要用swagger

swagger为前端和后端程序员提供了更为规范的API文档，减少在开发过程的各自产生的分歧！

3. 使用swagger有什么好处？

• 世界上最流行的API框架
• RESTful API文档在线自动生成器
• API文档和API定义同步更新
• 直接运行，可以在线测试API
• 支持多种语言，Java，C#，PHP等

2. 新建一个基于web的spring boot项目

测试最基本的环境：

编写controller

@RestController
@RequestMapping("hello")
public class HelloController {

    @RequestMapping("sayHello")
    public String sayHello(){
        return "Hello Swagger";
    }
}

访问：http://localhost:8080/hello/sayHello

环境搭建完成！

3. 导入swagger依赖

<!-- 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>

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

4. 自定义swagger-ui

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo getApiInfo(){
        Contact contact = new Contact("liuzeyu12a",
                "https://me.csdn.net/blog/JAYU_37",
                "515801535@qq.com");
        //没有set方法，所以只能通过构造器
        return new ApiInfo("liuzeyu12a`Blog",
                "即使再小的帆也能远航",
                "1.0",
                "https://me.csdn.net/blog/JAYU_37",
                contact, "Apache 2.0",
                "http://apche.org/licenses/LISCENSE-2.0",
                new ArrayList<>());
    }



}

5. 配置扫描接口

WithMethodAnnotation(GetMapping.class)：表示只扫描方法上加了GetMapping的get请求
WithClassAnnotation(Controller.class)：表示只扫描类上加上了@Controller的接口

除此之外还可以配置接口扫描过滤

实例：

    //配置swagger的docket实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(getApiInfo()).
                select().  //select配置扫描的接口
                apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")).
                paths(PathSelectors.ant("/haha/**")).  //扫描controller包下haha包下的接口
                build();
    }

接口的扫描位置在com.liuzeyu.controller包下的/haha下的任意接口！
此时写了一个控制类：

swagger界面：

6. 配置swagger开关

如果有一个需求，让swagger在生产环境下使用！

准备多生产环境

swagger配置：

    //配置swagger的docket实例
    @Bean
    public Docket docket(Environment environment){
        Profiles profiles = Profiles.of("dev","test");
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(getApiInfo()).
                enable(flag).
                select().  //select配置扫描的接口
                apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")).
                paths(PathSelectors.ant("/haha/**")).  //扫描controller包下haha包下的接口
                build();
    }

生产环境下可以正常使用swagger

如果注释掉# spring.profiles.active=dev

则关闭swagger

7. 配置API分组

一个分组对应这个一个Docket实例。所有如果需要多个分组，我们应当在容器中注入多个Docket实例。

    //配置swagger的docket实例
    //分组:liuzeyu
    @Bean
    public Docket docket(Environment environment){
        Profiles profiles = Profiles.of("dev","test");
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(getApiInfo()).
                enable(flag).
                groupName("liuzeyu").
                select().  //select配置扫描的接口
                apis(RequestHandlerSelectors.basePackage("com.liuzeyu.controller")).
                paths(PathSelectors.ant("/haha/**")).  //扫描controller包下haha包下的接口
                build();
    }
    @Bean
    public Docket docket_A(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket_B(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

实际开发中，不同的分组应当对应着不同的开发人员，这样大项目的接口开发分工就会更加明确！

8. 实体类配置

1. 准备实体类：

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

2. 提供接口，返回值必须是实体类类型！

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

3. 启动swagger
   

9. 常用注解

运用在实体类上的注解有
@ApiModel :为实体类添加注释
@ApiModelProperty：为实体类属性添加注释
在io.swagger.annotations下，还有一些常用的注解：

swagger注解	简单说明
@Api(tag=“xxxx模块说明”)	作用在类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiParam(“xxx”)	作用在j接口方法的字段上

主要目的就是为了生成友好的接口文档，让人跟容易阅读！

10. 小结

1. 我们可以通过swagger给一些比较难理解的属性或接口增加注释信息，便于理解！
2. 接口文档实时更新
3. 可以在线测试！

参考：https://www.bilibili.com/video/BV1PE411i7CV?p=50