SpringBoot中整合Swagger

SpringBoot中整合Swagger

Swagger就是一个API接口文档，方便前后端联调的一款工具。

1、创建SpringBoot项目

2、引入Swagger2的相关依赖

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

我这里只是列出的Swagger2的依赖，并没有列出其他依赖，其他依赖根据自己的需求添加

3、开启Swagger2

添加一个类SwaggerConfig专门配置Swagger，我们需要自定义Swagger的相关配置，但是这里我们先开启测试一下

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

记得加上@Configuration注解表示这是一个Spring的配置文件，@EnableSwagger2注解表示开启Swagger2

去浏览器测试一下，输入http://localhost:8080/swagger-ui.html

有了，说明我们开启成功，下面我们开始自定义相关配置

4、配置Swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo);
    }
    //配置自定义作者信息apiInfo
    @Bean(name = "apiInfo")
    public ApiInfo apiInfo(){
        return new ApiInfo(
                "wqk的swaggerAPI配置文档",
                "Api接口配置文档",
                "v1.0",
                "urn:tos",
                new Contact("wqk", "", "xxxxxxxx@gmail.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

我们先创建一个ApiInfo方法，返回一个ApiInfo对象，如果你不想自定义一些作者信息的话就不需要new一个，就直接用默认的就行了。然后用Spring的方法把他返回给Doccket方法，就会出现如下效果：

这里的作者的可定制化程度还是挺高的，可以自己尝试一下配置

然后加下来就是在docket方法里面自定义扫描包或者其他的

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                //开启Swagger，默认是false
                .enable(true)
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //扫描所有接口
                //.apis(RequestHandlerSelectors.any())
                //不扫描任何接口
                //.apis(RequestHandlerSelectors.none())
                //扫描控制器类方法上带有GetMapping注解的接口
                //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                //扫描控制器类上带有RequestMapping注解的接口
                //.apis(RequestHandlerSelectors.withClassAnnotation(RequestMapping.class))
                //扫描这个包里的接口
                .apis(RequestHandlerSelectors.basePackage("cn.wqk.swagger.controller"))
                //扫描这个请求路径的接口
                //.paths(PathSelectors.ant("/wqk/**"))
                .build();
    }
    //配置自定义作者信息apiInfo
    @Bean(name = "apiInfo")
    public ApiInfo apiInfo(){
        return new ApiInfo(
                "wqk的swaggerAPI配置文档",
                "Api接口配置文档",
                "v1.0",
                "urn:tos",
                new Contact("wqk", "", "a954278478@gmail.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

其中还有一些给控制器或者实体类加上注释的Api注解

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

@Api(tags = "Hello控制器")
@RestController
public class HelloController {
    @ApiOperation("hello接口")
    @GetMapping("/hello")
    public String hello(){
        return "HelloSwagger!";
    }
}

比如我给HelloController类加上@Api(tags = "Hello控制器")注解，给hello方法加上@ApiOperation("hello接口")注解，看看效果：

可以看到控制器和控制器里的方法都有了注释，这样前后端联调就会更加方便，其他注解你可以自行测试。

最后想特别谢谢一位up，狂神老师：https://space.bilibili.com/95256449?from=search&seid=15091236066275360244 讲的特别好，他的Mybatis，Spring，SpringMVC，SpringBoot个人感觉都讲得特别好，这篇就是他那节课的笔记。