SpringBoot 框架（九）—— SpringBoot 集成 Swagger

一、SpringBoot 集成 Swagger

1.1 创建项目并集成Swagger

1.1.1 创建项目

1.1.2 导入Swgger依赖

进入Maven官网，搜索springfox swagger

导入上述两个依赖

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

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

1.1.3 编写Config类

编写一个SwaggerConfig 作为SpringBoot中Swagger的配置

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

}

@EnableSwagger2直接的作用是开启Swagger2

编写完成后，启动项目，然后在浏览器访问http://localhost:8080/swagger-ui.html，即可进入到Swagger文档界面

自定义Swagger文档界面，在SwaggerConfig类中配置Swagger文档界面的相关信息

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

    /**
     * 配置Swagger 的 Docket 的 Bean 实例
     * @return
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    /**
     * 配置 Swagger 信息的 apiInfo
     */
    private ApiInfo apiInfo(){
        Contact contact = new Contact("痞猫尤加利的博客","https://blog.csdn.net/baidu_27414099","1234567@qq.com");
        return new ApiInfo(
                "Swagger Document",
                "Document For Swagger Demo",
                "v1.0",
                "https://blog.csdn.net/baidu_27414099",
                contact,
                "Apache 2.0",
                "http://www/apache.org/icenses/LICENSE-2.0",
                new ArrayList()
        );
    }

}

重启项目，再次在浏览器中访问，相关位置的修改已被修改

1.2 Swagger 相关配置

1.2.1 配置是否启动Swagger

在SwaggerConfig 类中可以配置是否启动Swagger

/**
 * 配置Swagger 的 Docket 的 Bean 实例
 * @return
 */
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false); //配置是否启动Swagger
}

• enable：false，则不启动Swagger，无法再浏览器中访问
  true，则启动Swagger

配置完成，再次启动后在浏览器访问则会出现以下界面

1.2.2 配置Swagger 扫描接口

/**
 * 配置Swagger 的 Docket 的 Bean 实例
 * @return
 */
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
            //.paths()
            .build();
}

RequestHandlerSelectors：配置要扫描的接口，有如下选项：

1. RequestHandlerSelectors.basePackage()：基于某一个包扫描，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
            .build();
}

配置后再次启动并访问，则出现以下界面，只有配置扫描的包下的接口会出现在界面中
2. RequestHandlerSelectors.withClassAnnotation()：扫描类上的注解，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .build();
}

上面的配置就只会扫描有RestController的类

3. RequestHandlerSelectors.withMethodAnnotation()：扫描方法上的注解，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
            .build();
}

上面的配置就只会扫描有GetMapping的方法

4. RequestHandlerSelectors.any()：扫描全部，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.all())
            .build();
}

5. RequestHandlerSelectors.none()：都不扫描，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.none())
            .build();
}

1.2.3 配置过滤器

Swagger 配置过滤器用paths()，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .paths(PathSelectors.ant("/test/**"))
            .build();
}

paths需要一个PathSelectors类型的参数，PathSelectors有如下选择

1. (PathSelectors.ant("")：如下表示只扫描并通过带有"/test/"的所有请求

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .paths(PathSelectors.ant("/test/**"))
            .build();
}

2. PathSelectors.regex()：表示利用正则表达式进行匹配
3. PathSelectors.any()：表示所有都通过
4. PathSelectors.none()：表示所有都不通过

1.2.4 配置Swagger 文档分组

配置Swagger 用groupName()，如下示例中，配置了多个分组

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

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

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

    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组4");
    }

启动项目并在浏览器中访问Swagger，得到如下界面，可以看到有四个分组可以选择

1.3 Swagger 配置 Models

1.3.1 默认配置Models

创建一个实体类UsersModel类如下

public class UsersModel {

    public int id;
    public String name;
    public int age;
    public String sex;
    
}

在TestController类中新增一个方法，用于返回UsersModel示例

@GetMapping(value = "/users")
public UsersModel usersModel(){
    return new UsersModel();
}

启动项目再次访问Swagger文档，如下

1.3.2 自定义配置Models

① 给实体类和字段上添加注释，如下

@ApiModel("客户实体类")
public class UsersModel {

    @ApiModelProperty("编号")
    public int id;
    @ApiModelProperty("姓名")
    public String name;
    @ApiModelProperty("年龄")
    public int age;
    @ApiModelProperty("性别")
    public String sex;

}

• @ApiModel("客户实体类")：给实体类添加注释
• @ApiModelProperty("编号")：给实体类的字段添加注释
  再次启动并访问，则出现以下界面，可以看大实体类和对应字段都有对应的说明，能够方便查看和使用
  
  ②给方法添加注释
  在方法上添加@ApiOperation()即可给该方法添加相应注释，如下示例，在TestController中再添加一个方法

@PostMapping(value = "/test1")
    @ApiOperation("test1方法")
    public String test1(){
        return "tes1";
    }

结果如下

给方法参数添加注释
在方法上添加@ApiParam()即可给该方法添加相应注释，如下示例，在TestController中再添加一个方法

 @PostMapping(value = "/test2")
    @ApiOperation("test2方法")
    public String test2(@ApiParam("str2参数注释")String str2){
        return "test2";
    }

结果如下

1.4 Swagger 测试

Swagger 可以利用浏览器直接测试接口，方便调试和查看错误

在Swagger 文档界面，点击Try it out，进入到测试界面

在测试界面，输入测试参数点击Excecute即可测试

测试结果如下，测试结果中包含测试返回信息，以及报错信息