Swagger（springboot学习13）

学习要点：

• 了解Swagger的作用及概念
• 了解前后端分离
• 在springboot中集成swagger

一、Swagger简介

前后端分离时代：

• vue+springboot
• 后端：控制层（controller）、服务层（server）、数据访问层（dao）
• 前端：前端控制层、视图层
  •  伪造后端数据，json，不需要后端也能运行整个项目
• 前后端交互方式——API
• 前后端相对独立，分耦合
• 前后端可以部署在不同的服务器上

交互产生的问题：

• 前后端集成联调，前端人员和后端人员无法做到即时协商（都是一个做就不存在这个问题了）

解决方案：

• 制定schema(计划)，实时更新API，降低集成的风险
• 早些年：制作word计划文档
• 前后端分离：
  • 前端测试后端接口（如：postman）
  • 后端提供接口，需要实时更新最新的消息以改动

那么Swagger就应运而生

• API框架
• RestFull风格的API，文档在线生成工具——API文档与API定义同步更新
• 直接运行，在线测试API接口（就是controller的RequestMapper请求映射）
• 支持多种语言

官网：https://swagger.io/

二、在项目中使用Swagger

在项目中使用swagger需要springfox

• swagger2
• swagger-ui

Springboot集成swagger

1、新建一个springboot-web项目

2、导入相关依赖

以后省事可以直接导一个启动器便可

淦，3.0版本的进不来测试页面，降级成2.9.2

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

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

3、编写helloword的请求控制器

表明项目构建成功，后面使用swagger

@RestController
public class HelloController {

    //项目的默认请求/error
    @RequestMapping("/hello")
    public String hello(){
        return "helloworld";
    }
}

 4、编写swagger配置文件——config

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

测试运行，因为swagger会有默认配置

@Configuration//注解标识这个类是一个spring的配置类
@EnableSwagger2 //开启swagger2，必须是2，1是老版的过时了
public class SwaggerConfig {
    
}

5、Swagger-ui页面分析 

以上就是springboot-web项目集成swagger，下面是配置swagger 

配置Swagger

1、配置Swagger信息

编写配置文件diamond

@Configuration//注解标识这个类是一个spring的配置类
@EnableSwagger2 //开启swagger2，必须是2，1是老版的过时了
public class SwaggerConfig {

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    //配置Swagger信息-apiInfo

    /*apiInfo接口信息：
      String title,标题
      String description,描述
      String version,版本
      String termsOfServiceUrl,终端地址
      String contactName,作直名字
      String license,许可证
      String licenseUrl许可证地址
     */
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "明哥的SwaggerAPI接口文档",
                "千江有水千江月，万里无云万里天",
                "1.0",
                "https://baidu.com",
                "明哥",
                "Apache 2.0",
                "https://baidu.com"
                );
    }
}

效果展示

 2、配置swagger扫描接口

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //requestHandlerSelector配置要扫描接口的方式
                    //basePackage指定要扫描的包
                    //any扫描全部
                    //none都不扫描
                    //withClassAnnotation扫描类上的注解
                    //withMethodAnnotation扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.ming.swagger.controller"))
                //paths过滤什么路径
                    //ant只扫描指定路径
                .paths(PathSelectors.ant("/ming/**"))
                .build();//build建造者模式
    }

效果，接口都被过滤了

3、配置是否启动Swagger

 效果展示

4、 应用场景分析：Swagger在生成环境中使用，在发布时不使用（也就是多套配置环境下）

解决思路：

• 判断是不是生成环境 boolean flag = false
• 注入enable（flag）

测试的时候，写两套配置环境，一套开发dev，一套发布prod，分别设置不同端口号

编写代码（指定访问生产环境） 开启swagger

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的项目环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处在自己设定的生成环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动Swagger，如果为false，则Swagger不能在浏览器中访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ming.swagger.controller"))
                //.paths(PathSelectors.ant("/ming/**"))
                .build();//build建造者模式
    }

效果展示

非指定配置环境访问则无法进入swagger

 5、配置API文档分组

.groupName("晴空")

注意：一个Docket代表一个分组

 前端页面

 配置多个分组，设置多个Docket实例

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("张三");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
    }
    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("王五");
    }

前端展示

 三、实体类配置

生成的api文档中的实体类加注释

1、创建实体类

//由于这里懒得写get/set，所有属性设置共有了
@ApiModel("用户实体类")//相当于别名，取代默认名字Models
public class User {
    @ApiModelProperty("用户名")//属性起别名——就是给生成的api文档中的实体类加注释
    public String username;
    @ApiModelProperty("密码")//属性起别名
    public String password;
}

2、编写controller

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

3、在controller中加注释

    //Operation接口，放在方法上
    @ApiOperation("Hello控制类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }

前端效果

也可以在里面测试try it out ↑

 4、总结：

1. 我们可以通过swagger给一些比较难理解的实体类加注释信息（这样，在看api接口文档时会方便一点）
2. 接口文档实时更新
3. 可以在线测试

注意：在正式发布，要关闭swagger，防止技术泄露，还能节省运行内存（它要动态生成api文档，很耗内存）