掌握Swagger

学习目标：

• 了解Swagger的作用和概念
• 了解前后端分离
• 在SpringBoot中集成Swagger

Swagger简介：
前后端分离
Vue+SpringBoot

后端时代：
前端只用管理静态页面；html ==>后端。模板引擎 => Jsp,后端是主力

前后端分离时代：

• 前端： 后端控制层，服务层，数据访问层
• 后端：前端控制层，视图层
• 前后端如何交互？ ==> API。
• 前后端相对独立，松耦合。
• 前后端甚至可以部署在不同的服务器上。

产生问题：
前后端集成联调，前端人员和后端人员无法做到"'及时协商，尽早解决"，最终导致问题集中爆发
解决方案：

1. 首先制定schema，实时更新API，降低集成风险。
2. 早些年，制定Word计划文档。
3. 前后端分离：
   前端测试后端接口：Postman
   后端提供接口，实时更新最新消息，及时改动

Swagger

• 号称最流行的API框架
• RestFul Api 文档在线自动生成工具=>文档与Api同步更新
• 直接运行，可以直接测试API接口
• 支持多种语言（java，PHP）
  官网：https://swagger.io/

在项目中使用Swagger需要springbox

• swagger2
• ui

SpringBoot集成Swagger

1. 新建一个SpringBoot-wed项目
2. 导入相关依赖

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


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

3. 编写一个hello工程
4. 配置Swagger ==> config

@Configuration
/**开启swagger*/
@EnableSwagger2
public class SwaggerConfig {
    
}

5.测试运行

配置Swagger

Swagger的Bean实例Docket

@Configuration
/**开启swagger*/
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        /**作者信息*/
       Contact contact =  new Contact("贺庆玉", "https://mp.csdn.net/console/article", "2214946614@qq.com");
        return new ApiInfo(
                "贺庆玉的Swagger文档",
                "再小的繁也能远航",
                "v1.0",
                "https://mp.csdn.net/console/article",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());

    }
}

Swagger配置扫描接口

 @Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                /**RequestHandlerSelectors  配置要扫描接口的方式
                 * basePackage  指定扫描的包*/
                .apis(RequestHandlerSelectors.basePackage("com.he.swagger.contorller"))
                .build();
    }

是否启动Swagger

enable true :开启 false : 关闭

@Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                /**是否启动Swagger配置*/
                .enable(false)
                .select()
                /**RequestHandlerSelectors  配置要扫描接口的方式
                 * basePackage  指定扫描的包*/
                .apis(RequestHandlerSelectors.basePackage("com.he.swagger.contorller"))
                .build();
    }

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

• 判断是否生产环境 flag =false
• 注入enable(flag)

配置文件

spring.profiles.active=dev

application-dev.properties

application-pro.properties

@Bean                             //扫描指定包
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profile = Profiles.of("dev","test");
        //environment.acceptsProfiles判断是否处自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profile);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                /**是否启动Swagger配置*/
                .enable(flag)
                .select()
                /**RequestHandlerSelectors  配置要扫描接口的方式
                 * basePackage  指定扫描的包*/
                .apis(RequestHandlerSelectors.basePackage("com.he.swagger.contorller"))
                .build();
    }

配置API文档的分组

.groupName("贺")

如何配置分组？ 多个Docket实例即可

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profile = Profiles.of("dev","test");
        //environment.acceptsProfiles判断是否处自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profile);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("贺")
                /**是否启动Swagger配置*/
                .enable(flag)
                .select()
                /**RequestHandlerSelectors  配置要扫描接口的方式
                 * basePackage  指定扫描的包*/
                .apis(RequestHandlerSelectors.basePackage("com.he.swagger.contorller"))
                .build();
    }

Swagger配置扫描接口

实体类

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String passwd;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPasswd() {
        return passwd;
    }

    public void setPasswd(String passwd) {
        this.passwd = passwd;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", passwd='" + passwd + '\'' +
                '}';
    }
}

controller

@RestController
public class helloController {

    @PostMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

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

    /**不是放在类上的，是放在接口*/
    @ApiOperation("hello2测试")
    @PostMapping("/hello2")
    public String hello2(@ApiParam("用户名") User userName){
        System.out.println("测试成功"+userName.getUsername());
        return "hello"+userName.getUsername();
    }
}

结果：