给Swagger换个皮肤,整合Knife4j文档

时间:2023-02-13 16:54:24

(目录)


前言

API 文档对接是前后端分离时代必不可少的一个环节,为了极大的提升效率,一个简洁、易用且美观的文档至关重要。最初,API 文档是一个纯手工编写的 Word。但是,程序猿是一群极具追求自动化高效率的人。于是,随着代码而启动的全自动化在线文档诞生了,其中最具代表性的当属 swagger。swagger 虽高效,但也有不足。knife4j 对 swagger 进行了封装,弥补了其中的不足,包括但不限于参数忽略,离线( md、html、doc、json )文档等等。可以说是满足并超出了一个 API 文档应有的自我修养。

关于 knife4j

knife4j 官网:

doc.xiaominfo.com/knife4j/

有两个大版本 3.X 和 2.X ,官方解释如下

给Swagger换个皮肤,整合Knife4j文档

界面赏析

给Swagger换个皮肤,整合Knife4j文档


动手实践

示例版本

工具 版本
SpringBoot 2.3.0.RELEASE
knife4j 3.0.2

1、引入依赖

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

2、swagger 配置类( knife4j 底层是 springfox)

如果你用过或正在使用 swagger 作为你的 API 文档,对这些代码应该不会陌生,因为它们并没有任何分别。

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 控制层包名,会自动扫描包里的所有接口
                .apis(RequestHandlerSelectors.basePackage("org.programlife2016.knife4j.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        // 展示在主页的信息
        return new ApiInfoBuilder()
                // 文档标题
                .title("knife4j")
                // 文档描述
                .description("knife4j示例文档")
                // 你的联系方式
                .contact(new Contact("ProgramLife2016", "xxx", "xxx"))
                // 文档版本
                .version("1.0")
                .build();
    }

}

3、实体类

@Getter
@Setter
@ToString
public class UserModel {

    @ApiModelProperty("主键")
    private Integer id;

    @ApiModelProperty("名称")
    private String name;

    @ApiModelProperty("年龄")
    private Integer age;

}

可以看到这里使用 @ApiModelProperty 注解替代了传统的 Java 注释knife4j 会读取注解的值来作为参数的说明展示在文档上,对接者就可以清晰明了字段代表的属性

给Swagger换个皮肤,整合Knife4j文档

4、控制层

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

    @Autowired
    private UserService userService;

    @ApiOperation("添加")
    @PostMapping("/add")
    public CommonResult<UserModel> add(@RequestBody UserModel userModel) {
        userService.add(userModel);
        return CommonResult.success();
    }

    @ApiOperation("更新")
    @PutMapping("/update")
    public CommonResult<UserModel> update(@RequestBody UserModel userModel) {
        userService.update(userModel);
        return CommonResult.success();
    }

}

这里使用到了两个注解 @Api 和 @ApiOperation。

@Api 是对整个类的说明,

@ApiOperation 是对单个接口的说明。

给Swagger换个皮肤,整合Knife4j文档


访问 knife4j 查看与调试接口

启动 SpringBoot 服务后浏览器访问 knife4j 就能看到‘界面赏析’中的效果图,地址为

http://127.0.0.1:8080/doc.html

knife4j 常用特性

knife4j 在 swagger 的基础上做了许多增强,这里介绍几个最常用的。

使用增强特性需在 application.yml 中开启

knife4j:
  enable: true

过滤请求参数

在增改接口中,有时我们为了方便(其实就是懒),会用同一个 model,但在新增接口中是不需要传递id的,修改接口中又是必传的,在 API 文档新增接口如果展示了这个字段就会莫名其妙,这时,过滤请求参数就显得尤为重要。在 knife4j 中,只需一个 @ApiOperationSupport 注解即可搞定。

@ApiOperation("添加")
@ApiOperationSupport(ignoreParameters = {"id"})
@PostMapping("/add")
public CommonResult<UserModel> add(@RequestBody UserModel userModel) {
    userService.add(userModel);
    return CommonResult.success();
}

给Swagger换个皮肤,整合Knife4j文档

全局参数

前后端分离开发中一般使用 token 作为请求参数进行身份与权限鉴定,有放在 query(表单)和 header(请求头)的,knife4j 对这两种都进行了支持,只需在侧边栏‘文档管理 -> 全局参数设置’中设置。

给Swagger换个皮肤,整合Knife4j文档

离线文档

有时我们需要一份离线文档可以随时随地进行查看,knife4j 支持导出四种格式( md、html、doc 、json)的离线文档,在侧边栏‘文档管理 -> 离线文档’中导出。

给Swagger换个皮肤,整合Knife4j文档