Knife4j - API文档生成神器

目录

一、Knife4j是什么？

二、使用步骤

---

一、Knife4j是什么？

         Knife4j是一个基于Swagger的开源API文档工具。它主要用于生成友好、简单、功能强大的API文档。通过在Swagger中定义API接口，Knife4j可以自动生成详细的API文档，包括接口定义、参数说明、返回值等。这些文档能够帮助开发人员更快地了解和使用API接口，从而提高开发效率。除了生成文档之外，Knife4j还提供了一个在线的API测试工具，可以方便开发人员直接在线测试API接口的功能和性能。

二、使用步骤

 在项目中引入Knife4j的依赖

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

​​​​​​application.properties中加入以下配置

# Enable Knife4j
knife4j.enable=true

# 开启权限认证(如果需要用户名密码登录)
knife4j.security.basic.enable=true
# 设置用户名
knife4j.security.basic.username=<your-username>
knife4j.security.basic.password=<your-password>

 在API方法上，需要添加@ApiOperation注解，用于描述API操作。例如：

@ApiOperation(value = "根据ID查询用户信息")
@GetMapping("/users/{id}")
public User getUser(@PathVariable("id") long id) {
   
}

还可以添加其他注解，用来描述API方法的请求方式、参数、响应等。例如，可以添加@ApiImplicitParam注解，用于描述API方法的参数： 

@ApiOperation(value = "根据ID获取用户信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "long")
@GetMapping("/users/{id}")
public User getUser(@PathVariable("id") long id) {
}

@ApiModel和@ApiModelProperty是用于描述数据模型和模型属性的注解。如果有一个“User”类，包含“id”、“name”和“email”属性，可以使用以下代码来描述： 

@Data
@Builder
@ApiModel(description = "用户")
public class User {
    @ApiModelProperty(value = "用户ID", required = true)
    private long id;

    @ApiModelProperty(value = "用户姓名", required = true)
    private String name;

    @ApiModelProperty(value = "用户邮箱", required = true)
    private String email;
}

 @ApiModel注解用于描述“User类信息，@ApiModelProperty注解用于描述每个属性的详细信息。

这些注解会被转换为文档，并显示在API文档中。

上述操作做完，启动服务之后在浏览器上访问 http://localhost:8080/doc.html 就可以看到API文档了，同时我们也可以在页面上进行接口测试。