• Knife4j使用流程
• Knife4j常用注解

在后端开发过程中当我们实现接口功能的时候，如果要测试的话，不仅要拼接URL地址，频繁的测试过程会不断拼接URL地址，为了解决这个问题我们使用APIfox来测试不行吗？这个当然是可以的，但要注意现在还是在测试阶段，代码逻辑还需要修改，如果频繁的修改就要不断手动同步我们的APIfox，所以使用Knife4来最为稳妥，一方面是Knife4j会自动扫描帮助我们完成开发文档的搭建，其次是同步性方面，Knife4j会自动在开发文档中更新代码逻辑，很方便我们进行临时快速的开发测试。

而Swagger也有同样的功能，可以这么说Knife4j其实是Swagger的Plus版本，而我们更加倾向于使用Knife4j的原因是其UI界面更加符合人类审美这一块

Knife4j使用流程

有两种方式，第一种是写好配置类，利用注释启动注释，之后在项目开启的时候就会自动扫描指定包内的@RequestMapping,@RequestController,@GetMapping@PostMapping这些映射注释和方法参数，根据映射注释来自动拼接好开发文档需要的请求URL地址和请求参数。如果想要往开发文档里面添加更多的注释方便阅读的话，下一标题的常用注释会提到，以下是简易的Knife4j搭建。

//创建好配置类
@Configuration
@EnableSwagger2  // 启用Swagger2（Knife4j基于此）
public class SwaggerConfig {

    // 配置Docket核心Bean
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) 
                .paths(PathSelectors.any())
                .build();
    }

    // 配置API基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API接口文档")  // 文档标题
                .description("系统开发接口文档")  // 详细描述
                .version("1.0.0")  // 文档版本
                .contact(new Contact("张三", "https://zhangsan.com", "zhangsan@example.com")) 
                .build();
    }
} 

之后的内容就很简单了，详情见下一标题。还有第二种方法，那就是使用配置文件来代替配置类，大体内容都差不多

knife4j:
  enable: true //开启Knife4j
  setting:
    language: zh-CN//开启中文
  openapi:
    title: 开发项目名称
    description: 描述开发项目具体内容
    version: 1.0.0
    concat:
    license: Apache License 2.0
    license-url: https://github.com/itwanger/paicoding/blob/main/License
    email: bangzewu@126.com
    group://
      admin:
        group-name: 后台接口分组
        api-rule: package//扫描哪些内容
        api-rule-resources://具体是哪个
          - com.github.paicoding.forum.web.admin
      front:
        group-name: 前台接口分组
        api-rule: package
        api-rule-resources:
          - com.github.paicoding.forum.web.front

我更倾向于推荐第二种，这样不需要显示的写出Dokcer组件，并且配置文件的形式可以说很便于修改了

Knife4j的常用注释

上文提到Knife4j能够自动生成开发文档是因为扫描了对应的注释，经过解析得到对应内容，其实还有更多的注释便于我们完成开发文档的详备，分别是

• @ApiOperation(name=”该接口的名称”，notes=“该接口的详细描述”，tags) 加在类上
• @Operation(summary=”该接口功能的名称”，description=“该接口功能的详细信息”) 加在类中的方法上
• @Parameter(required: 是否必填,description: 参数描述) 添加在参数列表中
• @Schema(description:描述属性是什么)应用于DTO/VO类的属性上，描述数据模型的字段。 这是让文档清晰展示数据结构的关键