接口文档[Knife4j]

接口文档[Knife4j]

接口文档是描述 API 接口的详细文档，通常用于沟通开发、测试和使用 API 的团队。一个好的接口文档不仅能够让开发人员明确接口的使用方法，还可以帮助使用者理解 API 的功能和预期行为。

Knife4j 使用，参考：https://doc.xiaominfo.com/docs/quick-start

swagger标准常用注解；

访问 http://ip:port/doc.html 即可查看接口文档

访问 http://ip:port/doc.html 即可查看接口文档

注解	标注位置	作用
@Tag	controller 类	描述 controller 作用
@Parameter	参数	标识参数作用
@Parameters	参数	参数多重说明
@Schema	model 层的 JavaBean	描述模型作用及每个属性
@Operation	方法	描述方法作用
@ApiResponse	方法	描述响应状态码等

方法一

添加依赖

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

创建application.yaml文件

# springdoc-openapi项目配置      
springdoc:
  api-docs:
    path: /api-docs  # 配置 OpenAPI 文档的路径
  swagger-ui:
    path: /swagger-ui.html  # 配置 Swagger UI 的路径
    enabled: true  # 启用 Swagger UI
    
  # 定制文档基本信息
  info:
    title: API 文档标题  # 设置文档标题
    description: API 文档描述  # 设置文档描述
    version: 1.0.0  # 设置 API 版本
    terms-of-service: https://example.com/terms  # 服务条款 URL
    
    # 关于开发者
    contact:
      name: 开发者姓名  # 开发者联系人姓名
      url: https://example.com/contact  # 联系方式 URL
      email: dev@example.com  # 开发者联系邮箱
      
    # 关于许可证
    license:
      name: Apache 2.0  # 许可证名称
      url: https://www.apache.org/licenses/LICENSE-2.0.html  # 许可证 URL
      
  # 定制服务器基本信息
  servers:
    - url: http://localhost:8080  # 服务器 URL
      description: 本地服务器  # 服务器描述
    - url: https://api.example.com  # 服务器 URL
      description: 生产服务器  # 服务器描述
      
  # 定制外部文档信息
  external-docs:
    description: 外部文档描述  # 外部文档描述
    url: https://example.com/docs  # 外部文档 URL
    
   #这里定义了两个分组，可定义多个，也可以不定义
  group-configs:
      #分组名
    - group: admin
      #按路径匹配
      pathsToMatch: /admin/**
      #分组名
    - group: user
      #按包路径匹配
      packagesToScan: com.hello.api.user
      
     
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

使用OpenAPI3的规范注解，注释各个Spring的REST接口

@RestController
@Tag(name = "名")  //本controller类的介绍
public class BodyController {
    
   @Operation(summary = "普通body请求") //方法的介绍
   @PostMapping("/body")
   public ResponseEntity<> body(@RequestBody FileResp fileResp){
       return ResponseEntity.ok();
   }
    
  @Parameters({
       @Parameter(name = "id", description = "员工id", in = ParameterIn.PATH,required = true) //参数的介绍
    })
    @Operation(summary="按照id查询员工信息")
    @GetMapping("/employee/{id}")
    public R get(@PathVariable("id") Long id){
        //进行脱敏以后返回给前端
        return R.ok(respVo);
    }
}

@Schema(description = "员工修改提交的数据")  //属性的描述
@Data
public class EmployeeUpdateVo {
    @Schema(description = "员工id")
    private Long id;
}

方法二

引入Maven 依赖

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

创建配置类

@Configuration
public class Knife4jConfiguration {
    //设置doc.html首先
    @Bean
    public OpenAPI openAPI() {
        Contact contact = new Contact();
        contact.setName("名字");
        return new OpenAPI()
                .info(new Info()
                        .title("hello-knife4j项目API")
                        .contact(contact)
                        .version("1.0")
                        .description("hello-knife4j项目的接口文档"));
    }
    
   //指定接口文档的分组
    @Bean
    public GroupedOpenApi userAPI(){
        return GroupedOpenApi.builder()
                .group("user")
                .displayName("用户接口")
                .pathsToMatch("/user/**").build();
    }

    @Bean
    public GroupedOpenApi loginAPI(){
        return GroupedOpenApi.builder()
                .group("login")
                .displayName("登录接口")
                .pathsToMatch("/login/**").build();
    }
}

启动项目

启动SpringBoot项目，访问http://localhost:8080/doc.html，观察接口文档。