Spring Boot 整合 Knife4j(快速上手)

关于 Knife4j

官方文档:https://doc.xiaominfo.com/
在这里插入图片描述

Knife4j是一个基于Swagger的API文档生成工具,它提供了一种方便的方式来为Spring Boot项目生成在线API文档。Knife4j的特点包括:

  • 自动化生成:通过Swagger注解,Knife4j可以自动解析API接口并生成对应的文档页面,无需手动编写文档。
  • 在线编辑和展示:Knife4j提供了在线编辑API文档的功能,可以方便地查看和测试API接口。
  • 可定制性:可以根据项目需求定制文档的展示样式和内容,满足不同项目的需求。
  • 方便集成:通过Spring Boot Starter的方式,可以方便地集成到Spring Boot项目中,无需额外的配置。

总之,Knife4j是一个方便、灵活且功能丰富的API文档生成工具,可以帮助开发团队快速生成和维护API文档。

整合 Knife4j

添加 Knife4j 依赖

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

配置 Knife4j 文档

第一种方式:Java 配置类

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    private ApiInfo commonApiInfo() {
        return new ApiInfoBuilder()
                .title("knife4j 接口文档测试")
                .description("Knife4j是一款基于Swagger的API文档在线编辑工具,它为Java开发人员提供了一种简单而强大的方式来创建、编辑和管理API文档。Knife4j可以帮助开发人员快速生成和展示API文档,提供了友好的界面和丰富的功能,包括接口测试、在线调试、文档管理等。它还支持对Swagger注解的解析,能够自动生成API文档,并提供了一些扩展功能,如接口权限设置、数据模型展示等。Knife4j可以帮助开发团队更好地管理和维护API文档,提高开发效率和协作能力。")
                .contact("hwike@foxmail.com")
                .version("1.0")
                .build();
    }

    @Bean(value = "dockerBeanAdmin")
    public Docket dockerBeanAdmin() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(commonApiInfo())
                //分组名称
                .groupName("后台接口分组")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.itwenke.springbootdemo.knife4j.admin"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    @Bean(value = "dockerBeanFront")
    public Docket dockerBeanFront() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(commonApiInfo())
                //分组名称
                .groupName("前台接口分组")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.itwenke.springbootdemo.knife4j.front"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

另一种方式:application.yml 配置

# knife4j
knife4j:
  # 是否开启
  enable: true
  setting:
    language: zh-CN
  openapi:
    title: knife4j 接口文档测试
    description: Knife4j是一款基于SwaggerAPI文档在线编辑工具,它为Java开发人员提供了一种简单而强大的方式来创建、编辑和管理API文档。Knife4j可以帮助开发人员快速生成和展示API文档,提供了友好的界面和丰富的功能,包括接口测试、在线调试、文档管理等。它还支持对Swagger注解的解析,能够自动生成API文档,并提供了一些扩展功能,如接口权限设置、数据模型展示等。Knife4j可以帮助开发团队更好地管理和维护API文档,提高开发效率和协作能力。
    concat: hwike@foxmail.com
    version: 1.0.0
    group:
      admin:
        group-name: 后台接口分组
        api-rule: package
        api-rule-resources:
          - com.itwenke.springbootdemo.knife4j.admin
      front:
        group-name: 前台接口分组
        api-rule: package
        api-rule-resources:
          - com.itwenke.springbootdemo.knife4j.front

配置属性:

  • enable:是否启用Knife4j
  • openapi:基本信息,例如标题、描述、版本
    • title:标题
    • description:描述
    • concat:作者
    • version:版本号
  • group:定义API分组
    • group-name:分组名称
    • api-rule:分组规则
    • api-rule-resources:指定包名

项目运行效果:

http://localhost:8080/doc.html

在这里插入图片描述

代码实现

示例一:

@Api(value = "测试控制器", tags = "测试API")
@RestController
@RequestMapping(path = {"api/test"})
public class TestController {

    @ApiOperation("打招呼")
    @GetMapping(path = "/hi")
    public String hi(@ApiParam(value = "姓名", required = true) @RequestParam String name) {
        return "hi " + name;
    }
}
  • @Api注解用于描述一个API接口的基本信息,包括接口的名称、描述、标签等。它可以用在Controller类上,表示对整个Controller的描述,也可以用在方法上,表示对单个方法的描述。

  • @ApiOperation注解用于描述一个API接口的操作,包括接口的名称、描述、响应信息等。它通常用在Controller的方法上,表示对该方法的描述。

  • @RequestParam注解用于将请求参数绑定到方法的参数上,指定请求参数的名称、是否必须、默认值等信息。它通常用在Controller的方法参数上,表示该参数是从请求中获取的参数。

效果展示:

在这里插入图片描述
在这里插入图片描述

示例二:

@ApiOperation("查询用户")
@GetMapping(path = "/query")
public UserInfoRespDTO query(UserInfoReqDTO reqDTO) {
    UserInfoRespDTO respDTO = new UserInfoRespDTO();
    respDTO.setUserId(1L);
    respDTO.setUserName(reqDTO.getUserName());
    respDTO.setRole("admin");
    return respDTO;
}
  • @ApiModel注解用于描述一个Java类,表示该类是一个API模型,用于在API文档中展示该类的信息,包括类的名称、描述、属性等。
  • @ApiModelProperty注解用于描述一个Java类的属性,表示该属性是一个API模型的属性,用于在API文档中展示该属性的信息,包括属性的名称、描述、数据类型、是否必须等。

效果展示:
在这里插入图片描述
在这里插入图片描述

权限认证

# knife4j
knife4j:
  # 是否开启
  enable: true
  # 权限认证
  basic:
    enable: true
    username: admin
    password: 123456

再次打开http://localhost:8080/doc.html,需要输入用户密码
在这里插入图片描述

生产屏蔽

# knife4j
knife4j:
  production: true

再次打开http://localhost:8080/doc.html,就不能访问了
在这里插入图片描述