springboot项目中使用knife4j

背景：项目需要自动生成接口文档，swagger很好但是knife4j更好，所以选择knife4j

1. pox文件中添加knife4j依赖

<!--添加Knife4j依赖-->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
  <version>4.1.0</version>
</dependency>

注意：因为knife4j已经包含了swagger，所以不需要在引入swagger，再引入可能造成冲突

2. 添加配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

/**
 * @author csn
 * @date 2024/1/10
 */

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    /**
     * 创建Docket实例
     * @return
     */
    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
        // 基本信息配置
        .apiInfo(apiInfo())
        // 文档的选择器
        .select()
        // 文档扫描的包路径(可以具体到控制器（com.mamba.order.controller），也可以这样com.mamba下的所有请求)
        .apis(RequestHandlerSelectors.basePackage("com.mamba"))
        // 哪些路径和API会生成文档，这里选择所有，也可以自己按需配置
        .paths(PathSelectors.any())
        .build();
    }

    /**
     * 文档信息配置
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
        // 文档标题
        .title("xxx项目")
        // 文档描述信息
        .description("API文档描述信息")
        // 文档版本号
        .version("1.0")
        .build();
    }

}

3. 添加一个接口

以登录接口为例，写完接口查看接口文档

3.1. 创建登录参数DTO

@Data
@ApiModel("用户登录")
public class LoginDTO {

    /**
     * 账号
     */
    @ApiModelProperty("账号")
    private String userName;

    /**
     * 密码
     */
    @ApiModelProperty("密码")
    private String password;

}

3.2. 创建接口Controller

@RestController
@RequestMapping("api/user")
@Api(tags = "用户管理")
public class UserController {

    @ApiOperation("登录")
    @PostMapping("/login")
    String login(LoginDTO loginDTO) {
        return "登录成功";
    }
    
}

常用注解说明:

• @ApiModel 用在模型类上,对模型类作注解
• @ApiModelProperty 用在属性上,对属性作注解
• @Api注解用于标注一个Controller
• @ApiOperation 注解用于HTTP方法进行描述

3.3. 运行项目查看api文档

http://127.0.0.1:8080/doc.html#/home

其中8080要改成自己项目的端口

api文档首页

登录接口文档页面

调试登录接口页面

大功告成 END!