springboot + vue前后端分离后台管理系统(三) -- 集成Knife4j

前言

对于开发人员来说，在开发过程中得自测是不可避免得，像postman这种工具就对模拟http请求提供了便捷。还有就是接口文档也是令人头疼得事情，Swagger就很好得解决了这种事情。

什么是Swagger？

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.
借助Swagger开源和专业工具集，为用户，团队和企业简化API开发。了解Swagger如何帮助您大规模设计和记录API。

Swagger选用

因为Swagger官方的API文档界面不好看，所以就找到了swagger-bootstrap-ui，界面好看还可以自定义请求参数文档。 后来又找到了该团队开发的springboot版本，在原有的基础上增强，Get it !
官网文档地址：https://doc.xiaominfo.com/knife4j/

引入

<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>2.0.8</version>
 </dependency>

3.x版本引用的是springfox3和OpenAPI3规范，目前是不稳定版本，所以选择引用2.x的版本~~~~

配置

新建SwaggerConfig.java

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

    @Bean(value = "api")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .description("# 文档的描述")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("1.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.ify.sampleAdmin.web.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

使用

接口添加swagger注解

@RestController
@RequestMapping("/user")
@Api(tags = "用户模块")
public class UserController extends BaseController {


    @GetMapping("/user")
    @ApiOperation(value = "获取根据ID获取用户")
    @ApiImplicitParam(name = "id",value = "用户id",required = true)
    public ResResult getUser(@RequestParam(value = "id") String id) {
        return ResResult.success();
    }
}

运行http://localhost:8181/sa/doc.html

• @Api(tags = "")：接口分组
• @ApiOperation(value = "")：接口名称
• @ApiImplicitParam(name = "id",value = "用户id",required = true)：接口参数声明

@ApiImplicitParam注解用在GET请求上是好用的，但是如果POST接口参数是对象时，会把不必要的参数都显示出来，例如

@PostMapping("/user")
@ApiOperation(value = "获取根据ID获取用户")
@ApiImplicitParam(name = "id",value = "用户id",required = true)
public ResResult getUser(User user) {
    return ResResult.success();
}

这是个POST接口，声明了只有一个id参数时必须传递的，参数是用User实体接收。结构swagger文档全部显示出来

当然Knife4j提供了过滤和包含参数的注解,可以排除或包含必须参数来简洁文档。

@ApiOperationSupport(ignoreParameters = {"id","orderDate.id"})

@ApiOperationSupport(order = 40,includeParameters = {"ignoreLabels","longUser.ids"})

但是，大多数人在开发接口的时候使用的传递参数都是Map或者JSONObject这类参数，Knife4j就提供了动态请求参数添加文档注释
例如：

@PostMapping("/user")
@ApiOperation(value = "post用户")
@DynamicParameters(properties = {
        @DynamicParameter(name = "id",value = "ID",example = "X000111",required = true,dataTypeClass = String.class),
        @DynamicParameter(name = "username",value = "用户名",required = true),
        @DynamicParameter(name = "password",value = "密码",required = true),
        @DynamicParameter(name = "sex",value = "性别",required = false),
})
public ResResult getUser(@RequestBody JSONObject params) {
    return ResResult.success();
}

swagger显示了必要的参数，并可以标明哪些参数是必传的！ 真是个不错的功能。

总结

Knife4j是对swagger-bootstrap-ui的升级，而swagger-bootstrap-ui是只是对官方界面的美化。Knife4j版本则包含了给官方swagger的功能并加以增强，个人认为很好用。