Spring Boot集成Swagger

Spring Boot集成Swagger

1、创建一个springboot的Web项目

2、导入依赖

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

3、创建SwaggerConfig配置文件

@Configuration //表明这是一个配置类
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
    
}

4、配置 Swagger 信息

4.1 配置Swagger的Docket的Bean实例

@Configuration //表明这是一个配置类
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
    /**
     * 1、配置了Swagger的Docket的Bean实例
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
    }
    /**
     * 2、配置Swagger的ApiInfo信息
     */
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Tenton", "https://blog.csdn.net/Tenton", "205723151@qq.com");
        return new ApiInfo(
                "Tenton的SwaggerApi文档", //文档标题
                "有理想，只要肯奋斗，终将会到达",  //文档描述
                "v1.0",  //文档版本
                "https://blog.csdn.net/Tenton",  //作者网站地址
                contact, //作者信息
                "Apache 2.0", //许可证
                "http://www.apache.org/licenses/LICENSE-2.0", //许可证Uri
                new ArrayList());
    }
}

4.2 配置扫描接口

@Configuration //表明这是一个配置类
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
    /**
     * 1、配置了Swagger的Docket的Bean实例
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                /**
                 *
                 * enable 是否启动Swagger，如果为False，则swagger不能在浏览器中访问
                 */
                .enable(true)
                .select()
                /**
                 * RequestHandlerSelectors  配置要扫描接口的方法
                 * basePackage("com.tenton.controller")  指定要扫描的包：com.tenton.controller 一般用此方法
                 * any(): 扫描全部
                 * none(): 都不扫描
                 * withClassAnnotation(GetMapping.class) : 扫描类上的注解，参数是一个注解的反射对象
                 * withMethodAnnotation(RestController.class) : 扫描方法上的注解
                 */
                .apis(RequestHandlerSelectors.basePackage("com.tenton.controller"))
                /**
                 * paths() 过滤什么路径
                 * ant：指定路径  一般用此方法
                 * any：过滤全部
                 * none：全部不过滤
                 * regex：按照正则表达式来过滤 
                 */
                .paths(PathSelectors.ant("/tenton/**"))
                .build();
    }
    /**
     * 2、配置Swagger的ApiInfo信息
     */
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Tenton", "https://blog.csdn.net/Tenton", "205723151@qq.com");
        return new ApiInfo(
                "Tenton的SwaggerApi文档",
                "有理想，只要肯奋斗，终将会到达",
                "v1.0",
                "https://blog.csdn.net/Tenton",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

4.3 设置要显示的Swagger环境 ,只允许开发（dev)和测试（test) 显示

@Configuration //表明这是一个配置类
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
    /**
     * 1、配置了Swagger的Docket的Bean实例
     */
    @Bean
    public Docket docket(Environment environment){
        /**
         * 3、设置要显示的Swagger环境
         */
        Profiles profiles = Profiles.of("dev","test");
        /**
         * 获取项目的环境
         * 通过environment.acceptsProfiles判断是否处在自己设定的环境中
         */
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                /**
                 *
                 * enable 是否启动Swagger，如果为False，则swagger不能在浏览器中访问
                 * 监听环境配置
                 */
                .enable(flag)
                .select()
                /**
                 * RequestHandlerSelectors  配置要扫描接口的方法
                 * basePackage("com.tenton.controller")  指定要扫描的包：com.tenton.controller 一般用此方法
                 * any(): 扫描全部
                 * none(): 都不扫描
                 * withClassAnnotation(GetMapping.class) : 扫描类上的注解，参数是一个注解的反射对象
                 * withMethodAnnotation(RestController.class) : 扫描方法上的注解
                 */
                //.apis(RequestHandlerSelectors.basePackage("com.tenton.controller"))
                /**
                 * paths() 过滤什么路径
                 * ant  一般用此方法
                 */
                //.paths(PathSelectors.ant("/tenton/**"))
                .build();
    }
    /**
     * 2、配置Swagger的ApiInfo信息
     */
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Tenton", "https://blog.csdn.net/Tenton", "205723151@qq.com");
        return new ApiInfo(
                "Tenton的SwaggerApi文档",
                "有理想，只要肯奋斗，终将会到达",
                "v1.0",
                "https://blog.csdn.net/Tenton",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

4.4 配置相应配置文件

application-dev.properties

#设置端口
server.port=8081

application-test.properties

#设置端口
server.port=8082

application.properties

# 当前项目环境为开发环境
spring.profiles.active=dev

4.5 配置API分组

@Configuration //表明这是一个配置类
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
    /**
     * 4、配置API分组
     */
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Java");//组名
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("SpringBoot");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("SSM");
    }
}

配置实体类

@ApiModel("用户实体")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    @ApiModelProperty("姓名")
    private String userName;
    @ApiModelProperty("密码")
    private String password;
}

控制类UserController

@Api(tags = "用户控制类接口")
@Controller
public class UserController {
    @ApiOperation("获取用户的接口")
    @PostMapping("/user")
    public User getUser(User user){
        return user;
    }
}

Swagger常用注解

Swagger的所有注解定义在io.swagger.annotations包下

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