SpringBoot集成Swagger

1、什么是Swagger

1、编写完Controller后生成接口文档，可以加上有相关的提示信息
2、可以在线测试接口
3、接口文档随着开发的进行实时更新

2、准备工作

1、新建一个SpringBoot项目，勾选上Spring Web

2、导入相关依赖

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

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

3、编写Controller

@RestController
public class HelloController {

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

    @PostMapping("/login")
    public User login(String name, String pwd){
        return new User(name, pwd);
    }
}

4、配置Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

5、测试运行

访问http://localhost:8080/swagger-ui.html，会跳转到以下页面

该页面在导入的包中，这是Swagger提供给我们进行接口测试的页面

3、配置Swagger

1、将Swagger的bean实例docket加入到Spring容器

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo(){
        Contact contact = new Contact("Rengar", "https://www.csdn.net/", "1257341673@qq.com");

        return new ApiInfo("Rengar的SwaggerAPI文档",//标题
                "Api Documentation",//描述
                "V1.0",
                "https://www.csdn.net/",//术语服务连接
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

2、访问http://localhost:8080/swagger-ui.html，会发现该页面的一些信息发生了改变
以上的代码配置对应图中的一些信息

4、配置扫描接口及开关

1、自定义扫描接口的范围

默认情况下是扫描所有接口
以下代码自己自定义扫描的范围

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //.enable(false)关闭这个功能（页面）
                .select()
                //basePackage("com.rengar.controller") 扫描com.rengar.controller这个包
                //any() 扫描所有接口
                //none() 全部不扫描
                //withClassAnnotation(RestController.class) 扫描类上带有RestController的所有接口
                //withMethodAnnotation(RequestMapping.class) 扫描类上带有RequestMapping的所有接口
                .apis(RequestHandlerSelectors.basePackage("com.rengar.controller"))
                //将路径以/rengar/开头的所有API写入接口文档
                //.paths(PathSelectors.ant("/rengar/**"))
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("Rengar", "https://www.csdn.net/", "1257341673@qq.com");

        return new ApiInfo("Rengar的SwaggerAPI文档",//标题
                "Api Documentation",//描述
                "V1.0",
                "https://www.csdn.net/",//术语服务连接
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

2、让Swagger只在开发环境中使用

如何让Swagger在开发环境下使用，上线是不使用？
1、创建多个环境配置


2、在配置类中指定Swagger显示的环境

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境 只在dev和test环境中显示
        Profiles profiles = Profiles.of("dev", "test");

        //判断是否在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//关闭这个功能（页面）
                .select()
                //basePackage("com.rengar.controller") 扫描com.rengar.controller这个包
                //any() 扫描所有
                //none() 全部不扫描
                //withClassAnnotation(RestController.class) 扫描类上带有RestController的所有
                //withMethodAnnotation(RequestMapping.class) 扫描类上带有RequestMapping的所有
                .apis(RequestHandlerSelectors.basePackage("com.rengar.controller"))
                //拦截这个请求 /rengar/下的所有请求
                //.paths(PathSelectors.ant("/rengar/**"))
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("Rengar", "https://www.csdn.net/", "1257341673@qq.com");

        return new ApiInfo("Rengar的SwaggerAPI文档",//标题
                "Api Documentation",//描述
                "V1.0",
                "https://www.csdn.net/",//术语服务连接
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

5、配置API分组

在容器里放入多个Docket,每个Docket设置一个唯一的groupName

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @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");
    }

    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境 只在dev和test环境中显示
        Profiles profiles = Profiles.of("dev", "test");

        //判断是否在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//关闭这个功能（页面）
                .groupName("Rengar")
                .select()
                //basePackage("com.rengar.controller") 扫描com.rengar.controller这个包
                //any() 扫描所有
                //none() 全部不扫描
                //withClassAnnotation(RestController.class) 扫描类上带有RestController的所有
                //withMethodAnnotation(RequestMapping.class) 扫描类上带有RequestMapping的所有
                .apis(RequestHandlerSelectors.basePackage("com.rengar.controller"))
                //拦截这个请求 /rengar/下的所有请求
                //.paths(PathSelectors.ant("/rengar/**"))
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("Rengar", "https://www.baidu.com/", "1257341673@qq.com");

        return new ApiInfo("Rengar的SwaggerAPI文档",//标题
                "Api Documentation",//描述
                "V1.0",
                "https://www.baidu.com/",//术语服务连接
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

分组后的效果

6、Model和接口文档的提示信息

1、在实体类加注解，让实体类也在swagger-ui.html页面的Model部分出现，并写上提示信息
（接口文档是给其他人看的，加上实体类和提示信息，方便阅读）

@ApiModel("用户实体类")
//将实体类加入到Swagger中，并标注为"用户实体类"
public class User {

    @ApiModelProperty("用户名")
    //该属性标注为"用户名"
    private String name;

    @ApiModelProperty("密码")
    //该属性标注为"密码"
    private String pwd;

    public User() {
    }

    public User(String name, String pwd) {
        this.name = name;
        this.pwd = pwd;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPwd() {
        return pwd;
    }

    public void setPwd(String pwd) {
        this.pwd = pwd;
    }
}

2、接口上也可以写相关的提示信息

@Api(tags = "Hello控制器")
@RestController
public class HelloController {

    @GetMapping("/hello")
    @ApiOperation("欢迎请求")
    public String hello(){
        return "hello~";
    }

    @PostMapping("/login")
    @ApiOperation("登录请求")
    //@ApiParam("用户名")给参数加上提示信息的时候，会使Swagger无法正常测试该接口
    public User login(String name, String pwd){
        return new User(name, pwd);
    }
}

在参数上加入提示信息会使该接口无法正常测试
测试接口时，先把@ApiParam("")（参数上的注释）删掉

7、利用Swagger测试接口

在线测试接口，输入数据（图中的name和pwd），查看放回的json（图中的Response body）