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

2021-10-14 10:19:13  晓掌柜  版权声明:本文为站长原创文章,转载请写明出处


一、前言

    在之前的项目中,在线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>

    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做一个简明使用教程的记录,其实官网还有支持到更多的功能,有兴趣的同学可以直接查阅官方文档。

    


最新评论: