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

Posted 2023-02-14

(目录)

---

前言

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

关于 knife4j

knife4j 官网：

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

界面赏析

---

动手实践

示例版本

工具		版本
SpringBoot		2.3.0.RELEASE
knife4j		3.0.2

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

如果你用过或正在使用 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();
    

@Getter
@Setter
@ToString
public class UserModel 

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

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

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

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

@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。

---

访问 knife4j 查看与调试接口

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

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();

全局参数

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

离线文档

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

---