【SpringBoot】SpringBoot整合Swagger2+Knife4j,简单使用三步搞定！！！

前言

老实说，我个人早期是不爱用Swagger的，什么即时更新，确实有这个优点。但是现在写接口文档的软件工具升级的非常快，写接口的速度一点也不慢，而且也能协同合作，界面甩了Swagger几条街。但是为什么我还是要使用Swagger呢？第一是架不住领导要求，这是硬伤。第二，由于加入了knife4j,确实比早期的Swagger好太多了，也是满足大部分需求的。第三，技多不压身嘛，毕竟Swagger比较简单，用起来只要记住那几个常用注解就可以了。话不多说，直接实操，按照下面步骤就可以成功使用上。

使用

导入注解

这里只要导入两个注解即可。

<!--springfox swagger官方Starter-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.1</version>
</dependency>
1
2
3
4
5
6
7
8
9
10
11
12

编写配置类

@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("这是标题")
                .description("这是描述")
                .version("1.0")
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

使用Swagger的相关注解

这个常用的注解得熟悉几个，比如以下列举，网上搜一搜，一下子就会了，我这里就不过解释了，直接上例子。

SwaggerController

@Api(value = "我是@Api注解的value属性",tags = {"swagger管理模块"})
@RequestMapping("/swagger")
@RestController
public class SwaggerController {

    @ApiOperation(value = "post请求,json类型请求")
    @PostMapping("json")
    public ResponseWrapper<TestSwaggerResponse> haveParams(@RequestBody TestSwaggerRequest request){
        ResponseWrapper responseWrapper = new ResponseWrapper();
        return responseWrapper;
    }

    @ApiOperation(value = "post请求,表单类型请求")
    @PostMapping("form")
    public ResponseWrapper<TestSwaggerResponse> formRequest(TestSwaggerRequest request){
        return new ResponseWrapper();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

TestSwaggerRequest

@Data
@ApiModel(description = "请求参数")
public class TestSwaggerRequest {

    @ApiModelProperty(value = "姓名",example = "张三",required = true)
    private String name;

    @ApiModelProperty(value = "地址",example = "福建福州")
    private String address;
}
1
2
3
4
5
6
7
8
9
10

TestSwaggerResponse

@Data
@ApiModel("接口数据返回对象")
public class TestSwaggerResponse {

    @ApiModelProperty(value = "姓名",example = "张三")
    private String name;

    @ApiModelProperty(value = "地址",example = "福建省福清市")
    private String address;

    @ApiModelProperty(name = "age",value = "年龄",example = "1")
    private Integer age;
}
1
2
3
4
5
6
7
8
9
10
11
12
13

启动

启动呢也很方便，看一下自己SpringBoot项目配置的端口号是多少，楼主自己的项目端口号是9001,因为是本机启动的，所以访问以下地址

http://127.0.0.1:9001/template/doc.html

特别说明

楼主是一个坚持使用JavaBean规范的人，不喜欢使用Map，或者说不是什么特殊的业务需求实在要用到Map,我本人是偏爱JavaBean的，我觉得这样可读性比较好，不喜勿喷。所以如果有喜欢用Map类型做入参的小伙伴们，我只能说，可能接口文档展示的东西没有那么好，当然也有解决办法，就是可以自定义注解，然后配合官方给的一个插件类进行相互使用，也可以完成，但是我觉得，如果这样一轮下来，得不偿失，太繁琐了。所以呢，我还是劝大家拥抱JavaBean吧，可读性强，还可以比较好的做数据校验和参数校验。