33.0、springboot-Swagger配置扫描接口以及开关、34.0、Swagger的分组和注释以及swagger对程序的测试

33.0、springboot-Swagger配置扫描接口及开关

        我们先来看看在SwaggerConfig.java文件：

package com.hkl.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

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

    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("hkl","https://blog.csdn.net/m0_52433668","[email protected]");

        return new ApiInfo(
                "hkl的swaggerAPI文档",
                "天道酬勤",
                "v1.0",
                "https://blog.csdn.net/m0_52433668",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

        管理是否启动Swagger，只需要在SwaggerConfig.java的docket()方法里的apiInfo后面.enable(false);或者.enable(true);即可

        他默认是开启状态如果我们设置为false就是关闭

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

        那么在真实的开发过程中，假如我们只希望Swagger在生产环境中使用，在发布的环境中不使用怎么办？只需要两步：

        第一步：获取当前的环境，判断一下是否为生产环境 flag = false;

        第二步：注入enable(flag);

        首先第一步用以下代码来获取一下当前环境，并且设置一下Boolean值,完整代码下滑查看

//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev","test");
//通过enviroment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);

        这里注意Environment 是 import org.springframework.core.env.Environment;包下的不要导错了

        再第二步用以下代码来设置enable();来判断是否启动swagger，完整代码下滑查看

.enable(flag)

        以下是SwaggerConfig.java文件完整代码：

package com.hkl.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment) {
        //设置要显示的Swagger环境，这里表示dev和test环境下才会启动Swagger
        Profiles profiles = Profiles.of("dev","test");
        //通过enviroment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                //RequestHandlerSelectors，配置要扫描接口的方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none:不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.hkl.controller"))
                //paths()过滤什么路径
                .paths(PathSelectors.ant("/hkl/**"))
                .build(); }
    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("hkl","https://blog.csdn.net/m0_52433668","[email protected]");
        return new ApiInfo(
                "hkl的swaggerAPI文档",
                "天道酬勤",
                "v1.0",
                "https://blog.csdn.net/m0_52433668",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

34.0、Swagger的分组和注释的实现以及Swagger对程序的测试

如何分组呢？

        分组只需要在SwaggerConfig.java类中的Docket()连式编程的后面加上  .groupName("hkl") 即可：

return new Docket(DocumentationType.SWAGGER_2)
        .groupName("hkl")

        想要配置多个分组就写多个Docket方法即可，记得把他们都注入要Bean中去，但是要注意一定不要重名不然会报错，如下：

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

        接口注释的实现：

        首先我们创建一个pojo实体类User.java

package com.hkl.pojo;

public class User {

    public String username;
    public String password;

}

这里注意实体类中的属性要为public才能被swagger访问到

        如果想要在swagger-ui.html页面models中能够查看到User.java实体类，那么我们需要在Controller控制类接口中，返回值存在实体类，他就会被扫描至Swagger文档中

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

        让我们看看如何在swagger中给类和属性加上注释

        给类的注释：@ApiModel【这个注解@Api(注释信息)和@ApiModel等价】

        给属性的注释：@ApiModelProperty

        加上注释的User.java实体类文件如下：

package com.hkl.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

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

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

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

        那如何给接口的方法加上注释呢？

        接口方法注释：@ApiOperation

        接口方法的参数的注释：@ApiParam

@ApiOperation("HelloController控制类/login登录接口")
@ResponseBody
@PostMapping("/login")
public User login(@RequestParam @ApiParam("用户名") String username, @RequestParam@ApiParam("密码") String password) {
    User user = new User();
    user.setUsername(username);
    user.setPassword(password);
    return user;
}

Swagger还有一个强大的功能，可以对程序进行测试

1.首先进入Swagger-ui.html页面找到我们写好的接口

2.然后输入相应的测试数据点击execute执行程序开始测试

3.查看测试结果

 

Swagger总结:
1.我们可以通过Swagger给一些比较难理解的属性或者接口，添加注释信息

2.swagger可以实现接口文档的实时更新

3.swagger可以在线测试程序

        Swagger是一个优秀的工具，几乎所有的大公司都有在使用它

        【注意】：产品在正式发布的时候要关闭Swagger,因为出于安全因素的考虑，以及运行内存的节省来看，都建议在发布的时候关闭swagger