在线API文档工具Knife4j简明使用教程

一、前言

在之前的项目中，在线api文档这一块一直使用的是swagger-ui这一款产品。但是其功能相对来说较为简单，而且没有我们一直想要的文档导出这一功能。为此我甚至尝试了解析swagger-ui的接口数据然后进行文档导出，但是实际效果并不是很理想。

后来我们get到了一款新的api工具：Knife4j，并准备在全项目中进行使用。

二、关于Knife4j

2.1、什么是Knife4j

他的前身是swagger-bootstrap-ui（一个简单的swagger-ui的皮肤项目），后面作者进行了升级整改，集成了swagger-ui的接口通用性解决方案。使得此项目能像匕首一样，小巧，轻快，便利。

附官方文档地址： Knife4j官方文档地址

三、Knife4j引入及相关配置

3.1、引入Maven

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

Java

Copy

3.2、创建Swagger配置项

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("GUANGMUHUA API")
                        .description("guangmuhua web api")
                        .termsOfServiceUrl("http://www.guangmuhua.com.com/")
                        .contact("958356609@qq.com")
                        .version("1.0")
                        .build())
                /* 分组名称 */
                .groupName("2.X版本")
                .select()
                /* 这里指定Controller扫描包路径 */
                .apis(RequestHandlerSelectors.basePackage("com.XXX"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

四、项目代码部分配置

4.1、实体类修改示例如下

这里可以定义参数的名称以及使用Hidden来配置是否在接口中显示字段等。

@Data
@TableName("syslog")
public class SysLogEntity implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty("数据ID")
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    @ApiModelProperty("用户名")
    private String username;

}

4.2、controller中代码如下

@RestController
@Api(tags = "测试控制类")
@RequestMapping("/test")
public class XaTestController {

    /**
     * 功能描述:knife4j测试
     * Param: [noteEntity]
     * Return: com.com.xa.guangmuhua_api.modules.modules.utils.R
     */
    @PostMapping("/knife4jTest")
    @ApiOperation("knife4j测试")
    public R knife4jTest(@RequestBody NoteEntity noteEntity) {
        return R.ok();
    }
}

五、效果展示

5.1、在线访问

浏览器访问： IP + 端口 + doc.html，进入在线api界面。如下：

5.2、支持离线文档导出

5.3、接口概述

5.4、接口在线调试

六、后记

这里暂时对Knife4j做一个简明使用教程的记录，其实官网还有支持到更多的功能，有兴趣的同学可以直接查阅官方文档。