knife4j文档入门指南

前言与介绍

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。而knife4j是集Swagger2 和 OpenAPI3 为一体的增强解决方案，增强扩展有了基于Springfox框架+Swagger2规范的自动注入的starter，可以说是非常方便。

简单来说，knife4j能方便后端程序员实现一份提供前端程序员或者其他开发者调用的接口文档，在接口更新后能及时更新，避免文档书写不及时带来交流的成本。当然，写一个好看的文档也是愉悦大家的心情。这是我选择knife4j而不是swagger的重要原因，swagger-ui实在充斥这一种老旧ui的感觉。

当然，我永远推荐大家参照官网，毕竟文章只是给出了一个可行的解决方案而不是一种思维，这里留下官网的地址Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)与Github源码地址xiaoymin/knife4j: Knife4j is a set of Swagger2 and OpenAPI3 All-in-one enhancement solution (github.com)。

简单小目录

• 导入依赖

• 相关配置

• 使用注解

• 效果展示

导入依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <!--保持版本与Knife4j v4.0的版本一致，避免jar包冲突，因为Knife4j-v4.0.0版本依赖的springdoc版本是1.6.9 -->
            <version>1.6.9</version>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-core</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
            <version>4.0.0</version>
        </dependency>

这里要注意knife4j与springdoc的版本问题，另外knife4j的增强功能对springboot的版本也有对应关系。本文只是简单介绍knife4j并不做深入研究使用knife4j的增强功能，所以就不放它们之间的对应版本了，如果将来用到了我会来更新的。

相关配置

配置类SpringDocConfig代码如下：

@Configuration
public class SpringDocConfig {
​
    @Bean
    public OpenAPI mallTinyOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("EasyDemo-API接口文档")
                        .description("EasyDemo-API接口文档，随便看看不要当真")
                        .contact(new Contact().name("被风吹散").email("601079657@QQ.com"))
                        .version("v0.0.2"));
    }
}

简单的信息填充，new了一个OpenAPI然后new一个Info填入相关信息，例如title、description等。

另外有些配置也可以在application.yml文件中增加，不过不加也没关系，下面给出我的示例。

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
    enabled: true
  api-docs:
    path: /v3/api-docs
    enabled: true
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: false

使用注解

以下注解均来自swagger-core依赖，可以参照源码学习更多功能。

接口-Controller层注解

注解	目标	参数	说明
@Tag	类	name、description等	将这个类增加到swagger文档中
@Operation	方法	summary、description、method等	书写具体接口的说明
@ApiResponses	方法	/	定义多个返回码，包含@ApiResponse注解
@ApiResponse	方法	responseCode、description等	定义一个返回码

@Tag(name = "UserController", description = "EasyDemo-用户服务-API接口")
@RestController
@RequestMapping("/api/user")
public class UserController {
​
    @Resource
    UserService userService;
​
    @Operation(summary = "login", description = "用户登录接口，使用账密登录", method = "POST")
//    @ApiResponses(//为单个接口配置多个返回码描述
//            @ApiResponse(responseCode = "400",description = "Bad Request")
//    )
    @PostMapping("/login")
    public Result login(@RequestBody LoginParam param) {
        String account = param.getAccount();
        String password = param.getPassword();
        User logined = userService.login(account, password);
        if (logined != null) {
            return Result.success(logined);
        }
        return Result.fail(501, "登录失败！");
    }
​
    @Operation(summary = "register", description = "用户注册接口，采用账号密码注册", method = "POST")
    @PostMapping("/register")
    public Result register(@RequestBody LoginParam param) {
        String account = param.getAccount();
        String password = param.getPassword();
        try {
            userService.register(account, password);
        } catch (Exception e) {
            System.out.println(e);
            return Result.fail(502, "注册失败！");
        }
        return Result.success();
    }
}

实体类-model层注解

注解	目标	参数	说明
@Schema	类和参数	description,required等	定义类或参数的文档

@Schema(description = "登录参数类")
@Data
public class LoginParam {
​
    @Schema(description = "登录的账号",required = true)
    private String account;
​
    @Schema(description = "输入的密码",required = true)
    private String password;
}

效果展示

输入localhost:8080/doc.html

这是knife4j的页面

 

输入localhost:8080/swagger-ui.html

 

输入localhost:8080/v3/api-docs