SpringBoot——Swagger

Swagger

号称世界上最流行的API框架

Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新

直接运行，在线测试API

支持多种语言 （如：Java，PHP等）

官网：https://swagger.io/

SpringBoot继承Swagger

1. 创建springboot项目，导入依赖

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

2. 创建一个配置类

@Configuration
@EnableSwagger2  //开启Swagger2自动配置
public class SwaggerConfig {

}

3. 测试
   打开http://localhost:8080/swagger-ui.html
   

配置Swagger

@Configuration
@EnableSwagger2  //开启Swagger2自动配置
public class SwaggerConfig {

    // Swagger实例
    @Bean
    public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo);
    }
    
    
    @Bean
    public ApiInfo apiInfo() {
        // contact是作者信息
        Contact contact = new Contact("wcy", "https://www.baidu.com", "836680474@qq.com");
        return new ApiInfo(
                "API文档",    // 标题
                "测试文档",   // 描述
                "1.0",        // 版本号
                "urn:tos",    // 组织链接
                contact,      //作者信息
                "Apache 2.0", // 许可
                "https://www.apache.org/licenses/LICENSE-2.0",  // 许可链接
                new ArrayList()// 扩展
        );
    }
}

此时打开就是我们配置的信息


可以看到他扫描到了我们的控制器路由和默认的路由/error
他默认扫描了所有的接口
这个我们可以配置

配置扫描接口

1. 通过apis()来指定

@Bean
public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo) {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            .select()
            // 扫描指定包
            .apis(RequestHandlerSelectors.basePackage("com.wcy.controller"))
            .build();
}

在配置了指定的包后，只能扫描到我们自己的Controller

RequestHandlerSelectors还有如下几种配置

• any() 全部扫描
• none() 全部不扫描
• withClassAnnotation() 扫描类上的指定注解

// 类上的RestController注解
RequestHandlerSelectors.withMethodAnnotation(RestController.class)

• withMethodAnnotation() 扫描方法上指定注解

// 扫描方法上的GetMapping注解的路由
RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)

2. 通过paths()指定

此时的配置为先扫描RestController注解，然后在检查是否有/user/开头的请求

@Bean
public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo) {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            .select()
            // 扫描指定包
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            // 指定扫描的路径
            .paths(PathSelectors.ant("/user/**"))
            .build();
}

PathSelectors也有可选项

• any() // 任何请求都扫描
• none() // 任何请求都不扫描
• regex(final String pathRegex) // 通过正则表达式控制
• ant(final String antPattern) // 路径

配置Swagger开关

是否启用swagger

• enable(true) 开
• enable(false) 关

// Swagger实例
@Bean
public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo) {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            // swagger开关
            .enable(false)
            .select()
            // 扫描指定包
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            // 指定扫描的路径
            .paths(PathSelectors.any())
            .build();
}

设置为false时会为如下界面

特定环境启用Swagger

配置当项目处于test、dev环境时显示swagger，处于prod时不显示

// Swagger实例
@Bean
public Docket docket(
        @Qualifier("apiInfo") ApiInfo apiInfo,
        Environment environment) {
        
    // 获取环境的配置文件
    String[] activeProfiles = environment.getActiveProfiles();
    // swagger开关
    boolean flag = false;
    
    // 判断
    for (String activeProfile : activeProfiles) {
        // prop则为false
        if ("prop".equals(activeProfile)) break;
        // 如果是test或dev则开启swagger
        if ("test".equals(activeProfile) || "dev".equals(activeProfile)){
            flag = true;
            break;
        }
    }
    
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            // swagger开关 根据环境配置文件来决定
            .enable(flag)
            .select()
            // 扫描指定包
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            // 指定扫描的路径
            .paths(PathSelectors.any())
            .build();
}

spring.profiles.active=prod # 此时不会开启
spring.profiles.active=test # 会开启

或则也可以这样

@Bean
public Docket docket(
        @Qualifier("apiInfo") ApiInfo apiInfo,
        Environment environment) {
   // 1 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 2 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean flag = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            // swagger开关 根据环境配置文件来决定
            .enable(flag)
            .select()
            // 扫描指定包
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            // 指定扫描的路径
            .paths(PathSelectors.any())
            .build();
}

多个API分组

默认的api分组的名称为default，可以通过指定groupName()来指定

return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo)
        // swagger开关 根据环境配置文件来决定
        .enable(flag)
        .groupName("wcy")   // 分组名称
        .select()
        // 扫描指定包
        .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
        // 指定扫描的路径
        .paths(PathSelectors.any())
        .build();

多个分组配置多个Docket即可，可以在不同的Docket中配置不同的操作操作

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

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("分组B");
}

@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("分组C");
}

实体配置

• @ApiModel为类添加注释

• @ApiModelProperty为类属性添加注释

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

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

    @ApiModelProperty("密码")
    public String password;
}

在controller中返回User就可以将其映射到Model中

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

常用注解

Swagger注解	说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

@ApiOperation("接口")
@GetMapping("/hello1")
public String hello1(@ApiParam("返回这个名字") String name){
    return "hello"+ name;
}

皮肤

默认

bootstrop

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

layerui

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>