11_Swagger

一. 引言

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

二. SpringBoot集成Swagger

2.1 创建SpringBoot项目

• 正常创建即可

2.2 导入依赖

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

2.3 编写一个hello工程

• SwaggerController.java
• 运行启动类, 测试是否可以正常运行

package com.dz.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SwaggerController {

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

2.4 配置Swagger

• config目录下新建SwaggerConfig

package com.dz.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

}

2.5 测试

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

三. 配置Swagger

• Swagger的bean实例Docket

3.1 配置Swagger信息

• Docket.apiInfo()

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("dz","https://www.cnblogs.com/MRASdoubleZ/","java137@163.com");
        return new ApiInfo(
                "dz的SwaggerAPI文档",
                "学无止境",
                "1.0",
                "https://www.cnblogs.com/MRASdoubleZ/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());

    }

}

3.2. Swagger配置扫描接口

• Docket.select()

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors: 配置要扫描接口的方式
                //basePackage: 指定要扫描的包
                //any(): 扫描全部
                //none(): 不扫描
                //withClassAnnotation: 扫描类上的注解, 参数是一个注解的反射对象
                //withMethodAnnotation: 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.dz.controller"))
                //paths(): 过滤什么路径
                .paths(PathSelectors.ant("/dz/**"))
                .build();
    }

}

3.3 配置是否启用Swagger

• Docket.enable(false), 表示不启用Swagger

//配置了Swagger的Docket的bean实例
//enable(false), 表示不启用Swagger
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(false)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.dz.controller"))
        //.paths(PathSelectors.ant("/dz/**"))
        .build();
}

• 在开发环境(dev)和测试环境(test)中启用Swagger, 在发布环境(pro)中不启用Swagger
• Profiles profiles = Profiles.of("dev","test");
• boolean flag = environment.acceptsProfiles(profiles);
• Docket.enable(flag)

//配置了Swagger的Docket的bean实例
//enable(false), 表示不启用Swagger
@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.dz.controller"))
        //.paths(PathSelectors.ant("/dz/**"))
        .build();
}

3.4 配置Swagger的分组

• Docket.groupName("dz")

@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("dz")
        .enable(flag)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.dz.controller"))
        //.paths(PathSelectors.ant("/dz/**"))
        .build();
}

• 配置多个分组
  • 多个Docket实例即可

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("dz1");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("dz2");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("dz3");
}

3.5. Api注释

3.5.1 实体类

• User

package com.dz.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

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

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

3.5.2 Controller

package com.dz.controller;

import com.dz.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;

@RestController
public class SwaggerController {

    @GetMapping("/hello")
    public String hello(){
        return "hello swagger";
    }

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

    //@ApiOperation不是放在类上的, 而是方法上
    @ApiOperation("Hello控制类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello" + username;
    }

    @ApiOperation("Post测试类")
    @PostMapping("/p")
    public User p(@ApiParam("用户名") User user){
        int i = 5/0;
        return user;
    }
}

• 总结:
  1. 我们可以通过Swagger给一些比较难理解的属性或接口增加注释信息
  2. 接口文档实时更新
  3. 可以在线测试
• 注意: 在正式发布的时候, 关闭Swagger!!! 出于安全考虑, 而且节省运行的内存