Swagger3.0.0配置

一、依赖

        
        
            io.springfox
            springfox-swagger2
            3.0.0
        
        
        
            io.springfox
            springfox-swagger-ui
            3.0.0
        
        
        
        
            io.springfox
            springfox-boot-starter
            3.0.0
        

二、默认配置swagger

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

}

http://localhost:8080/swagger-ui/index.html

界面如下：

swagger默认配置界面.png

三、自定义配置：

3.1 swagger信息配置：

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

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

    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("loong","http://www.loong.com", "--");
        return new ApiInfo(
                "自定义标题",
                "Api文档描述",
                "1.0.0",
                "http://www.loong.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

swagger自定义配置信息.png

3.2 扫描路径配置

    @Bean
    public Docket docket(Environment environment) {
        // 获取项目的环境 需要创建多个application-xx环境配置文件
         String[] profiles = environment.getActiveProfiles();
         System.out.println("当前环境");
        for (String temp : profiles) {
            System.out.println(temp);
        }
        Boolean enableSwagger = false;
        if (profiles.length > 0 && profiles[0].equals("dev")) {
            enableSwagger = true;
        }
        System.out.println("swagger是否开启：" + enableSwagger);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 是否启用swagger, false: 不能在浏览器访问
                .enable(enableSwagger)
                .select()
                // RequestHandlerSelectors, 配置要扫描接口的方式
                // basePackage: 指定要扫描的包
                // any(): 扫描全部
                // none(): 不扫描
                // withClassAnnotation: 扫描类上的注解, 参数是一个注解的反射对象 withClassAnnotation(RestController.class)
                // withMethodAnnotation: 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.loong.controller"))
                // paths 过滤什么路径 不显示到swagger文档中
                // .paths(PathSelectors.ant("/loong/**"))
                .build();
    }

3.3 配置多个分组

    // 配置多个分组
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("loong-A");
    }
    // 配置多个分组
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("loong-B");
    }
    // 配置多个分组
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("loong-C");
    }

    @Bean
    public Docket docket(Environment environment) {
        // 获取项目的环境
         String[] profiles = environment.getActiveProfiles();
         System.out.println("当前环境");
        for (String temp : profiles) {
            System.out.println(temp);
        }
        Boolean enableSwagger = false;
        if (profiles.length > 0 && profiles[0].equals("dev")) {
            enableSwagger = true;
        }
        System.out.println("swagger是否开启：" + enableSwagger);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("loong")
                .enable(enableSwagger)
                .select()
               .apis(RequestHandlerSelectors.basePackage("com.loong.controller"))
                .build();
    }

3.4 实体类配置

// 添加实体类注释
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }
}

@RestController
public class HelloController {

    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    public String hello() {
        return "hello, world.";
    }

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

    @ApiOperation("greeting 请求")
    @GetMapping("/greeting")
    public String greeting(@ApiParam("昵称") String name) {
        return "hi " + name;
    }
}

只要我们的接口中，返回值存在实体类，他就会被扫描到Swagger中。

四、总结

1. 我们可以通过 Swagger 给一些比较难理解的属性或者接口，添加注释信息
2. 接口文档实时更新
3. 可以在线测试

注意：在线上环境，记得关闭Swagger，处于安全考虑。而且节省运行的内存。