JavaEE（22）SpringBoot--Swagger

1. Swagger介绍

1. 前后端分离
（1）前后端分离

前端：控制层、视图层
后端：控制层、服务层、数据访问层
前后端通过API进行交互
前后端相对独立且松耦合

（2）产生的问题：前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

2. Swagger介绍

号称世界上最流行的API框架
Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
直接运行，在线测试API
支持多种语言 （如：Java，PHP等）
官网：https://swagger.io/

2. SpringBoot集成Swagger

1. 集成Swagger
（1） 创建一个SpringBoot-web项目
（2） 添加maven依赖

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

（3） 编写HelloController，确保运行成功

@RestController
public class HelloController {

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

（4）要使用Swagger，编写一个SwaggerConfig的配置类

@Configuration  //配置类
@EnableSwagger2  //开启Swagger的自动配置
public class SwaggerConfig {
}

（5）测试访问：http://localhost:8080/swagger-ui.html

2. 配置Swagger
（1）Swagger实例Bean是Docket，所以通过Docket实例来配置Swagger

@Configuration  //配置类
@EnableSwagger2  //开启Swagger的自动配置
public class SwaggerConfig {
    
    @Bean
    public Docket docket(){   //配置docket已配置Swagger的具体参数
        return new Docket(DocumentationType.SWAGGER_2);
    }
    
}

（2）可以通过apiInfo()属性配置文档信息

//配置文档信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字","http://xxx.xxx.com/联系人访问连接","联系人邮箱");

        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

（3）Docket实例关联apiInfo()

（4）测试访问

3. 配置扫描接口
（1）构建Docket时通过select()方法配置怎么扫描接口

@Configuration  //配置类
@EnableSwagger2  //开启Swagger的自动配置
public class SwaggerConfig {

    @Bean
    public Docket docket(){   //配置docket已配置Swagger的具体参数
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()   //通过select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.nelws.controller"))
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字","http://xxx.xxx.com/联系人访问连接","联系人邮箱");

        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

}

（2）重启项目测试，由于我们配置的根据包路径扫描接口，所以我们只能看到一个类

（3）除了通过包路径配置扫描接口，还可以通过其他方式扫描接口

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

4. 配置Swagger开关
（1）通过enable()方法配置是否启用Swagger，如果是false，Swagger就不能在浏览器中访问

（2）动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示

5. 配置API分组
（1）如果没有分组，这里默认default

（2）通过groupName()配置分组

（3）测试查看

（4）配置多个分组：即配置多个Docket即可

@Configuration  //配置类
@EnableSwagger2  //开启Swagger的自动配置
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment){   //配置docket已配置Swagger的具体参数

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("1组")  //配置分组
                .enable(true)    //配置是否启动swagger，false不启用
                .select()   //通过select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.nelws.controller"))
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字","http://xxx.xxx.com/联系人访问连接","联系人邮箱");

        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("2组");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("3组");
    }
    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("4组");
    }
    @Bean
    public Docket docket5(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("5组");
    }

}

（5）测试查看

6. 实体配置
（1）新建一个实体类

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体")  //@ApiModel为类添加注释
public class User {

    @ApiModelProperty("用户名")   //@ApiModelProperty为类属性添加注释
    private String name;
    @ApiModelProperty("年龄")
    private int age;

}

（2）只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中

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

（3）重启查看测试

（4）常用注解